Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

docs: define contribution intake workflow (#3006)

Francesco Bonaccibf7ee4b44058
diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml
new file mode 100644
index 0000000000..4a6b88b7a2
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug.yml
@@ -0,0 +1,106 @@
+name: Bug report
+description: Report reproducible incorrect behavior in Cua
+title: "[Bug]: "
+labels:
+ - bug
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Search existing issues and pull requests before filing. Describe the observed
+ behavior and evidence rather than only a proposed fix. Do not include credentials,
+ private application data, sensitive screenshots, or vulnerability details. Use
+ [private vulnerability reporting](https://github.com/trycua/cua/security/advisories/new)
+ for suspected security issues. File one problem per issue; open separate
+ issues for unrelated bugs.
+
+ - type: dropdown
+ id: area
+ attributes:
+ label: Primary area
+ options:
+ - Cua Driver
+ - SDK or bindings
+ - MCP or agent integration
+ - CLI
+ - Lume
+ - Containers or images
+ - Documentation
+ - Build, packaging, or release
+ - Other
+ validations:
+ required: true
+
+ - type: textarea
+ id: summary
+ attributes:
+ label: Summary
+ description: Describe the incorrect behavior in one or two sentences.
+ validations:
+ required: true
+
+ - type: textarea
+ id: reproduction
+ attributes:
+ label: Reproduction
+ description: Provide the smallest numbered steps or example that reproduces the behavior. If it is intermittent, say how often you observe it.
+ placeholder: |
+ 1. ...
+ 2. ...
+ 3. ...
+ validations:
+ required: true
+
+ - type: textarea
+ id: expected
+ attributes:
+ label: Expected behavior
+ description: What observable result did you expect?
+ validations:
+ required: true
+
+ - type: textarea
+ id: actual
+ attributes:
+ label: Actual behavior
+ description: What happened instead? Include exact structured errors when available. If you do not know the cause, say so rather than guessing a diagnosis.
+ validations:
+ required: true
+
+ - type: textarea
+ id: environment
+ attributes:
+ label: Environment
+ description: Include the component/package and version or commit, operating system and architecture, plus the application, browser, window system, or container image when relevant.
+ placeholder: |
+ Cua component and version/commit:
+ Operating system and architecture:
+ Application/browser/window system/image:
+ validations:
+ required: true
+
+ - type: textarea
+ id: evidence
+ attributes:
+ label: Evidence
+ description: Add redacted logs, error text, screenshots, recordings, or a minimal repository that help prove the behavior. Write "None available" when no additional artifact exists.
+ validations:
+ required: true
+
+ - type: textarea
+ id: workaround
+ attributes:
+ label: Workaround and additional context
+ description: Describe any workaround, regression range, suspected area, or related issue or pull request.
+
+ - type: checkboxes
+ id: checks
+ attributes:
+ label: Submission checks
+ options:
+ - label: I searched for duplicate issues and active pull requests.
+ required: true
+ - label: This issue describes a single problem.
+ required: true
+ - label: I removed credentials, private data, sensitive screenshots, and vulnerability details from this public report.
+ required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000000..e9db742518
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+ - name: Security vulnerability
+ url: https://github.com/trycua/cua/security/advisories/new
+ about: Report suspected vulnerabilities privately. Do not open a public issue.
+ - name: Question or contributor help
+ url: https://discord.com/invite/mVnXXpdE85
+ about: Ask questions and get help from the Cua community.
+ - name: RFC guidance
+ url: https://github.com/trycua/cua/blob/main/rfcs/README.md
+ about: Check whether a public contract or architecture change needs an RFC.
diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml
new file mode 100644
index 0000000000..d0c382fb0e
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature.yml
@@ -0,0 +1,83 @@
+name: Feature request
+description: Describe a user problem or product improvement
+title: "[Feature]: "
+labels:
+ - enhancement
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Describe the user problem and desired outcome before proposing an implementation.
+ Use the **Request for comments** form when the change affects a public SDK, CLI,
+ MCP, protocol, compatibility, permission, security, or cross-component
+ architectural contract.
+
+ - type: dropdown
+ id: area
+ attributes:
+ label: Primary area
+ options:
+ - Cua Driver
+ - SDK or bindings
+ - MCP or agent integration
+ - CLI
+ - Lume
+ - Containers or images
+ - Documentation
+ - Build, packaging, or release
+ - Cross-component
+ - Other
+ validations:
+ required: true
+
+ - type: textarea
+ id: problem
+ attributes:
+ label: User problem
+ description: Who encounters the problem, in which workflow, and what is its impact?
+ validations:
+ required: true
+
+ - type: textarea
+ id: desired_outcome
+ attributes:
+ label: Desired outcome
+ description: Describe the observable behavior or success condition you want.
+ validations:
+ required: true
+
+ - type: textarea
+ id: workaround
+ attributes:
+ label: Current workaround
+ description: How do users handle this today, if at all?
+
+ - type: textarea
+ id: scope
+ attributes:
+ label: Affected components and platforms
+ description: List known packages, applications, operating systems, compatibility boundaries, or integrations.
+
+ - type: textarea
+ id: alternatives
+ attributes:
+ label: Alternatives and prior art
+ description: Link related issues, RFCs, tools, or standards and note why they do not solve the problem.
+
+ - type: textarea
+ id: implementation
+ attributes:
+ label: Implementation ideas
+ description: Optional. Share implementation ideas only after describing the problem and outcome.
+
+ - type: checkboxes
+ id: checks
+ attributes:
+ label: Submission checks
+ options:
+ - label: I searched for existing issues, RFCs, and active pull requests.
+ required: true
+ - label: I reviewed the RFC criteria and used the RFC form instead when this requires a public contract or architectural decision.
+ required: true
+ - label: This public request contains no credentials, private data, sensitive screenshots, or vulnerability details.
+ required: true
diff --git a/.github/ISSUE_TEMPLATE/rfc.yml b/.github/ISSUE_TEMPLATE/rfc.yml
index 914175e01d..4fd4251fdb 100644
--- a/.github/ISSUE_TEMPLATE/rfc.yml
+++ b/.github/ISSUE_TEMPLATE/rfc.yml
@@ -9,8 +9,10 @@ body:
value: |
Use this form for public API, CLI, MCP, protocol, cross-platform architecture,
permission, security, compatibility, or multi-component decisions. Search for
- existing proposals first. Do not disclose vulnerabilities, credentials, private
- user data, partner context, or sensitive screenshots in a public issue.
+ existing proposals first. Report suspected vulnerabilities through
+ [GitHub private vulnerability reporting](https://github.com/trycua/cua/security/advisories/new).
+ Do not disclose vulnerabilities, credentials, private user data, partner context,
+ or sensitive screenshots in a public issue.
The issue is the discussion and decision record. If the proposal needs a longer
specification or diagrams, add a linked `rfcs/<issue>-<short-name>.md` pull request
@@ -98,7 +100,7 @@ body:
id: security
attributes:
label: Security, privacy, permissions, and telemetry
- description: Identify permission boundaries and data that must never be collected or exposed. Use private security reporting for vulnerabilities.
+ description: Describe the intended permission and trust boundaries and data that must never be collected or exposed. Do not describe an exploitable defect in shipped code; report that privately instead.
validations:
required: true
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000000..3dbc4ced6c
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,43 @@
+<!--
+Keep this description current as scope and evidence change. Do not include
+credentials, private user data, sensitive screenshots, or vulnerability details.
+Preserve external contributor authorship when their code or design ships.
+While this pull request is a draft, use this description as the live record of
+scope, progress, blockers, and evidence rather than posting periodic status comments.
+-->
+
+## Summary
+
+- Problem this solves:
+- What changed:
+
+<!-- Describe observable behavior. Do not narrate the diff file by file. -->
+
+## Related work
+
+<!-- Use Fixes only when this PR fully resolves the issue. Otherwise use Refs. -->
+
+Refs #
+
+RFC (required for a public SDK, CLI, MCP, protocol, compatibility, permission,
+or cross-component contract change):
+
+## Compatibility and risk
+
+- User-visible, API/CLI/MCP, migration, permission, or platform impact:
+- Risk and rollback:
+
+## Validation
+
+- Focused tests and checks:
+- Manual or platform evidence:
+- Known gaps or CI still required:
+
+## Contributor and release checks
+
+- [ ] The PR is focused and the description matches the final diff.
+- [ ] This change does not require an RFC, or the accepted RFC is linked above.
+- [ ] Tests, documentation, and platform evidence are included or the gap is explained.
+- [ ] The PR title is a Conventional Commit describing the production change.
+- [ ] External contributor authorship is preserved, or no external contribution is included.
+- [ ] If release-tracked files changed but this is intentionally non-releasing, the `no-release` label is applied.
diff --git a/AGENTS.md b/AGENTS.md
index 484d63c405..b6a66f40b8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,6 +23,39 @@ Preserve contributor credit when external code or design ships in Cua.
Do not reimplement submitted work solely to remove its authorship history.
+## Issue and pull request workflow
+
+The human-facing contribution contract lives in [`CONTRIBUTING.md`](CONTRIBUTING.md),
+the GitHub issue forms, [`rfcs/README.md`](rfcs/README.md), and
+[`SECURITY.md`](SECURITY.md). Keep those files canonical instead of duplicating
+their field lists or RFC lifecycle here.
+
+Coding agents act as workers within that contract, not as a planning authority.
+GitHub holds the durable record: the issue or RFC carries the problem and the
+decision, and the pull request carries the execution. Local schedulers, queues,
+and worktree tooling are private conveniences; a reviewer must not need them to
+understand, reproduce, or continue the work.
+
+- treat an open issue as intake, not evidence that the work is scheduled or
+ ready to implement. Selection must be visible in GitHub through an issue
+ assignment, a maintainer scope reply, or maintainer review of a linked draft
+ pull request;
+- before substantial edits, search for duplicates and active pull requests,
+ establish a narrow scope and observable acceptance evidence, and open one
+ linked draft pull request early. Do not start a second workstream for an issue
+ with an active linked pull request; contribute there or state why it is being
+ superseded;
+- use one issue or RFC as the problem/decision record and one isolated branch
+ or worktree per implementation workstream;
+- keep the linked pull request description current with scope, progress,
+ validation evidence, known gaps, and blockers instead of posting noisy
+ periodic status comments;
+- use `Refs #123` unless the pull request fully resolves the linked issue, in
+ which case use an issue-closing keyword; and
+- route suspected vulnerabilities through the private process in
+ [`SECURITY.md`](SECURITY.md), never a public issue, RFC, pull request, log, or
+ screenshot.
+
## Cross-platform Cua Driver behavior
Treat user-visible Cua Driver behavior as a cross-platform contract. Implement
@@ -66,8 +99,7 @@ macOS: libs/cua-driver/tests/runners/macos-lume/run-all.sh
```
- Prefer the GitHub-hosted Windows workflow when its strict preflight proves an
- interactive desktop. Do not assume that GitHub-hosted Windows runs in Session
- 0. Azure RDP is an optional environment-parity replay, not the canonical gate.
+ interactive desktop. Do not assume that GitHub-hosted Windows runs in Session 0. Azure RDP is an optional environment-parity replay, not the canonical gate.
- Use the GitHub-hosted Linux X11 workflow for the supported Linux gate. Keep
Nix source checks and compositor-specific Wayland lanes as their documented
separate gates.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ddd5ef6a85..86230fb498 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,9 +5,49 @@ SDKs, a Rust desktop driver, Swift virtualization tools, container images, and
public documentation. Start with the component that owns the behavior you want
to change.
+## Choose Where Work Starts
+
+| You want to | Start with |
+| ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Report reproducible incorrect behavior | The **Bug report** issue form |
+| Describe a user problem or product improvement | The **Feature request** issue form |
+| Change a public contract, compatibility policy, permission boundary, or cross-component architecture | The **Request for comments** issue form and [`rfcs/README.md`](rfcs/README.md) |
+| Report a suspected vulnerability | [GitHub private vulnerability reporting](https://github.com/trycua/cua/security/advisories/new), following [`SECURITY.md`](SECURITY.md) |
+| Ask for contributor help | The [Cua Discord community](https://discord.com/invite/mVnXXpdE85) |
+
+The issue tracker is an intake queue and historical record, not a promise that
+every open item is scheduled or ready for implementation. An open issue means
+the report was received. It does not mean anyone is working on it, and it does
+not reserve the work.
+
+Before substantial implementation:
+
+1. Search open issues and pull requests for the same problem. If an active pull
+ request already exists, contribute there or explain why your pull request
+ supersedes it.
+2. Comment on the issue with the scope you intend to implement and the
+ acceptance evidence you will produce.
+3. Open a draft pull request as soon as you have a branch and link it to the
+ issue. The linked draft pull request is the visible claim marker that helps
+ prevent duplicate work.
+
+Selection must be visible in GitHub through an issue assignment, a maintainer
+reply confirming the scope, or maintainer review of the linked draft pull
+request. Small, self-contained fixes may go directly to a focused pull request
+when the problem and evidence are clear; until reviewed, that work is an
+unselected contribution. Work that needs an RFC waits for the recorded decision
+in [`rfcs/README.md`](rfcs/README.md) before implementation begins.
+
+Once implementation starts, keep the issue or RFC as the problem and decision
+record and the pull request as the current execution record. Link them in both
+directions and keep the pull request description current as scope, validation,
+or known gaps change. Use `Refs #123` for related work. Use `Fixes #123` only
+when merging the pull request will fully resolve that issue.
+
## Report a Bug
-Before opening an issue, search the existing issue tracker. Include:
+Before opening the **Bug report** issue form, search the existing issue tracker.
+Include:
- a concise description and reproducible steps;
- expected and actual behavior;
@@ -19,9 +59,9 @@ Do not include credentials or private application data.
## Propose a Change
-For feature requests, describe the user problem and the expected behavior
-before prescribing an implementation. Mention affected platforms and existing
-workarounds when known.
+In the **Feature request** issue form, describe the user problem and the
+expected behavior before prescribing an implementation. Mention affected
+platforms and existing workarounds when known.
Use the [RFC process](rfcs/README.md) before implementation when a proposal
changes a public SDK, CLI, MCP, protocol, compatibility, permission, or
@@ -38,6 +78,14 @@ GitHub issue form. Longer proposals and diagrams remain in this repository under
5. Run the formatters and linters owned by the changed component.
6. Open a focused pull request that explains behavior, validation, and known gaps.
+### Agent-Assisted Contributions
+
+Agent-assisted pull requests are welcome and are held to the same standard as
+any other contribution. The person who opens the pull request is accountable
+for it: read and understand the diff, be able to explain why each change is
+present, and run the checks claimed in the description. Generated output or a
+successful tool response is not validation evidence by itself.
+
Use a Conventional Commit title because the squash-merge title becomes the
release entry. `fix(cua-driver): preserve input while reconnecting` produces a
patch release, `feat(lume): add a VM readiness probe` produces a minor release,
diff --git a/README.md b/README.md
index aec3acb30e..673be50619 100644
--- a/README.md
+++ b/README.md
@@ -174,6 +174,7 @@ of Setup Assistant on its first display boot; see [issue #2155](https://github.c
- [Blog](https://cua.ai/blog) — Tutorials, updates, and research
- [Discord](https://discord.com/invite/mVnXXpdE85) — Community support and discussions
- [GitHub Issues](https://github.com/trycua/cua/issues) — Bug reports and feature requests
+- [Security](SECURITY.md) — Private vulnerability reporting
## Citation
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000000..8dc4313439
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,35 @@
+# Security Policy
+
+## Report a Vulnerability
+
+Do not open a public issue, RFC, discussion, or pull request for a suspected
+vulnerability. Use [GitHub private vulnerability reporting](https://github.com/trycua/cua/security/advisories/new)
+so the report reaches the maintainers without disclosing details publicly.
+
+Include the smallest amount of information needed to investigate:
+
+- the affected Cua component and version or commit;
+- the operating system, environment, and configuration when relevant;
+- a concise reproduction or proof of the behavior;
+- the security impact and conditions required to trigger it; and
+- any known mitigation or workaround.
+
+Do not include credentials, tokens, private user or customer data, or unrelated
+sensitive material. Redact logs and screenshots before attaching them. Please
+avoid public disclosure until maintainers have coordinated remediation and an
+appropriate disclosure timeline with you.
+
+Maintainers will use the private report to acknowledge the finding, request any
+missing evidence, coordinate remediation, and discuss attribution. Security
+reporter attribution remains private until disclosure is permitted.
+
+To propose or debate a security boundary—such as a permission model, trust
+boundary, or public contract that does not disclose an exploitable defect—use
+the **Request for comments** issue form and [`rfcs/README.md`](rfcs/README.md).
+Use private reporting for a specific exploitable defect in shipped code or
+configuration. When design and vulnerability details are entangled, report
+privately first; maintainers can open or unblock the public RFC after remediation
+is coordinated.
+
+For incorrect behavior without a security impact, use the repository's **Bug
+report** issue form instead.
diff --git a/rfcs/README.md b/rfcs/README.md
index 633a8d3797..aec9f997e5 100644
--- a/rfcs/README.md
+++ b/rfcs/README.md
@@ -25,6 +25,19 @@ internal refactors that preserve public behavior, or urgent private security
response. Suspected vulnerabilities must use the repository's private security
reporting path instead of a public RFC.
+### Security design versus vulnerability reports
+
+A public RFC is the right place to decide what a security boundary should be:
+which process holds a capability, what a permission prompt must state, which
+data must not be collected or exposed, and how authorization appears in a
+public contract. A vulnerability report describes a specific exploitable defect
+in shipped Cua code or configuration. Design the boundary in public; report the
+defect privately through [`SECURITY.md`](../SECURITY.md).
+
+If a hardening proposal cannot be described without disclosing an exploitable
+defect, report it privately first. Maintainers can open or unblock the public
+RFC after remediation is coordinated.
+
## Repository structure
```text
@@ -68,15 +81,15 @@ shorter window, record the reason in the decision summary.
## Status vocabulary
-| Status | Meaning |
-| --- | --- |
-| `draft` | The author is still shaping the proposal. |
-| `review` | The proposal is ready for technical and product feedback. |
-| `accepted` | The decision is approved; implementation may still be pending. |
-| `completed` | The accepted proposal's required implementation has shipped. |
-| `declined` | Review concluded that Cua should not adopt the proposal. |
-| `withdrawn` | The author stopped the proposal before a decision. |
-| `superseded` | A linked later RFC replaces this decision. |
+| Status | Meaning |
+| ------------ | -------------------------------------------------------------- |
+| `draft` | The author is still shaping the proposal. |
+| `review` | The proposal is ready for technical and product feedback. |
+| `accepted` | The decision is approved; implementation may still be pending. |
+| `completed` | The accepted proposal's required implementation has shipped. |
+| `declined` | Review concluded that Cua should not adopt the proposal. |
+| `withdrawn` | The author stopped the proposal before a decision. |
+| `superseded` | A linked later RFC replaces this decision. |
## Review expectations