See the development runbook for the initial checkout, development commands, tests, and platform-specific desktop packaging prerequisites.
We are not actively seeking outside contributions and have limited review capacity. Opening a PR does not create an obligation to review or merge it. We may close or defer it, ask for a smaller scope, or reimplement the idea later. Meeting this guide's requirements makes a PR eligible for deeper review; it does not guarantee acceptance.
These requirements apply to every open PR, including drafts. Draft status does not postpone triage or excuse missing approval, unfocused scope, or inadequate verification. A draft can be closed for the same reasons as a ready PR; converting a PR to draft does not exempt it from reassessment.
Focused bug fixes, reliability fixes, performance improvements, and maintenance work are the most likely to be accepted. Unsolicited features, opinionated rewrites, and unrelated cleanup are not.
Report bugs in issues. Feature requests and proposals belong in Ideas discussions. Search existing reports, discussions, and documented workflows before starting work.
Outside the focused exceptions below, features and intentional changes to product behavior require a prior discussion with explicit maintainer approval of the direction and scope. Link the approval itself in your PR. A linked issue or discussion alone is insufficient. Calling a behavior change a bug fix does not exempt it from this requirement. Acceptance of a problem does not approve every implementation or promise a merge.
For a substantial bug fix, link an issue that maintainers have triaged to establish the actual failure and intended behavior. For other non-trivial work outside the exceptions below, agree on direction and scope with maintainers in an Ideas discussion before implementing it.
A very small, focused fix for an obvious bug can be submitted without a prior issue or discussion. Explain the defect and why the fix qualifies for this exception. We judge purpose, behavioral impact, and the changes needed to fix it. There is no line-count or file-count cutoff. A shared-contract fix may need changes across several clients; a few lines changing product defaults may require a discussion.
A focused configuration option for an established capability may also be eligible without prior feature approval. Explain the existing capability, what the option controls, and why its scope stays within that capability. Adding a setting does not by itself make a PR a new feature, and this route does not depend on proving an obvious bug. Judge its purpose and effects: new workflows, changed product defaults, and broader behavior choices still require approval, even when exposed as settings. The one-problem and verification requirements still apply; deeper review may reject the proposed configuration mechanism on design or correctness grounds.
Choosing an executable path for an already-supported hosting CLI can fit this configuration route. Keeping Files open as a separate tab alongside file previews changes tab lifetime and navigation, so it needs prior product-direction approval. Good verification does not replace that approval.
If an existing workflow already solves the reported need, difficulty finding or understanding it can still be a useful documentation, onboarding, or discoverability problem. Describe that problem. Maintainers decide the response; it does not automatically justify the proposed feature or behavior change.
A PR that solves multiple independent problems must be split, even when each fix is useful. Count the underlying problems, not the linked issues. Several reports may describe the same defect.
Include the contract, server, client, test, and documentation changes needed for that one problem. Explain their relationship when it is not obvious. An adjacent cleanup, refactor, or second fix needs its own PR unless it is necessary to solve the same problem. A large diff alone does not establish that the PR contains unrelated work.
This rule is for outside contributions. Maintainers, the logins in .github/TRIAGE_EXEMPTIONS.td, may batch related fixes in one PR.
Follow the documentation rules. Keep internal docs for decisions and hard-to-discover constraints. Update user guides when how to use a feature changes; skip descriptions of obvious controls and cosmetic changes.
Explain how you established the problem, how you checked the change, and what you observed. Give the relevant reproduction steps, environment, focused test commands or manual checks, and their results. State what you could not check. A checkbox or "tests pass" alone does not show that the change works.
Match the evidence to the change. Use focused tests for behavior that can be tested and manual evidence where appropriate. Do not substitute broad test runs for checking the affected behavior, or run repo-wide checks just to satisfy this guide. A backend fix does not need unrelated UI evidence.
UI changes require clear before/after screenshots. Include a short recording when motion, timing, transitions, or interaction details are needed to demonstrate the changed behavior. Attach or link evidence in the PR; do not commit PR-only screenshots or recordings to the repository.
Missing or demonstrably inadequate evidence can cause closure. A reviewer being unable to reproduce a well-documented platform-specific bug does not by itself invalidate the report. We assess the problem, scope, approval, and evidence, not an author's writing style or whether we think an agent wrote the PR.
Contribution triage checks whether the problem is established, any required approval is present, the scope is coherent, and the evidence is adequate. It inspects enough code to support that decision. Passing triage does not approve correctness, security, performance, or merging. Those need deeper review. Updates to the PR can change its eligibility and require reassessment.
PRs receive vouch:* contributor-status labels and size:* diff-size labels. These are context, not
eligibility rules. Vouching through .github/VOUCHED.td is separate from permission
to bypass triage. Only the GitHub logins explicitly listed in
.github/TRIAGE_EXEMPTIONS.td bypass triage. Organization membership,
vouching, collaborator or bot status, repository write access, and previous successful PRs do not
establish an exemption. Other contributors, including vouched contributors, go through triage.
Passing once does not grant permanent trust.
Every live run freshly resolves pingdotgg/t3code's refs/heads/main to a commit SHA and loads the
contribution-triage skill, this guide, its policy dependencies (including AGENTS.md documentation
rules), and the exemption list from that same SHA. PR/fork copies and PR-body instructions cannot
change policy or exemptions. Missing, incomplete, or malformed trusted files leave routing unresolved;
they do not grant an exemption, establish an empty list, or permit automatic closure or review handoff.
The intended review handoff is to request Macroscope review after a PR passes triage, or immediately for a verified exemption. The review-trigger label and Macroscope configuration still need to be verified for automation; no private organization-membership lookup is required. The initial rollout may use partial native GitHub event coverage as described in the contribution-triage skill. Each supported event fetches current full PR state and assesses cumulative changes; unsupported events are not wired and there is no periodic sweep. This guide does not announce a deployed automation or change existing review settings. Neither triage nor a Macroscope review authorizes merging.
Automated triage leaves a PR open for maintainer decision if someone in the trusted
TRIAGE_EXEMPTIONS.td list has commented or submitted a review,
including on an earlier head, or if triage:keep-open is present. This protection does not imply
eligibility or review approval.
PRs that violate these requirements can be closed before deeper review. Multiple independent fixes require splitting. Missing approval requires maintainer discussion or issue triage, as applicable. Missing evidence requires establishing the problem and showing how the change was checked.
Every policy-based closure must identify the specific rule, cite the evidence supporting the finding, link the relevant section of this guide, and explain how to address it for reconsideration. For example, identify the independent fixes to split or the exact missing verification. Correct the deficiency and request reconsideration, or submit the focused replacement PRs linked to the original.
An unclear relationship between changes needs investigation and, if still unexplained, a specific request for an explanation. Uncertainty alone is not proof of unrelated work. Access failures, incomplete retrieval, or an unfinished assessment are reasons to retry the assessment, not close a PR. If the proposed solution is declined but the report reveals a useful problem, preserve that problem for maintainer consideration. Feedback should be firm, specific, and free of insults or accusations about how the contribution was written.