Proof Portal

Sign in
Project overview

Omarchy

ProbeLabs65 findings · 95 requirements

A proof layer — requirements, tests and verified fixes — for two of Omarchy's subsystems: the application menu (launcher scripts, QML model, JSONC config, search and selection) and the lock screen (lock scripts, QML, PAM authentication). Scope is deliberately limited to those components of omacom/omarchy; the rest of the distribution is not covered.

Inbox
ReportR-2116GitHub issuePublicReceived

Unify contributor guidelines via single source of truth (AGENTS.md / CONTRIBUTING.md)

Reported by codenamekt · filed Sep 30, 2026Closed upstream on 2026-09-30 by its own reporter codenamekt, as not planned. Closed by its own reporter — not by itself evidence of a fix.

Open at source
Received and recorded verbatim. Nothing has been checked yet.

At a glance

1 · What is claimed?
Only the report text below — no validator has restated it as checkable claims yet.
2 · What does it affect?
Not yet mapped to any requirement or component.
3 · Is it reproducible?
No validation has been run yet.
4 · What remains unclear?
  • Not validated yet: no claims, no reproducer.
5 · What happens next?
Our staff decide whether the report is valid. Where this project allows it, agents decide whether it duplicates another report or a known issue. No decision has been recorded yet.

Original report

Unify contributor guidelines via single source of truth (AGENTS.md / CONTRIBUTING.md)revision 1 · captured 2026-09-30 01:46 UTC via poll

Background & Current State

Currently, contributor and agent guidance across the repository is split, and several open PRs are addressing parts of the same problem:
- #9095 proposes adding a # Pull Requests section to AGENTS.md instructing contributors to search open PRs for duplicates before coding.
- #8609 addresses checking open PRs/issues, verifying against the default branch (quattro), and testing caveats in default/agents/skills/omarchy/contributing.md.
- #6959 adds required checkboxes to bug.yml for duplicate searches and updates diagnose-crash/reporting.md.
- #6718 refines the agent skills around contribution vs installed customization.

Furthermore, GitHub surfaces CONTRIBUTING.md in its UI when contributors open issues or pull requests, but no root CONTRIBUTING.md exists in the repository.

Proposal: Single Source of Truth (AGENTS.md + symlink)

Rather than maintaining separate guides for humans and AI agents or fragmenting guidance between skills and root docs:

  1. Keep `AGENTS.md` as the single authoritative document for all contributors (humans and agents alike), updated with:
  • Duplicate Searches (No Dupes): Explicit requirement to search both open and closed issues and PRs (gh search issues, gh pr list --search) before writing code or filing reports.
  • Routing (Where to send what): Clear demarcation between GitHub Issues (validated bugs), GitHub Discussions (feature requests/suggestions), and Discord (support/debugging questions).
  • Branch Targeting: Clarify branching from and targeting the active default branch (quattro).
  • Testing & Verification: Running ./test/all (./test/cli + ./test/shell), writing tests in test/shell.d/, and visual verification for UI/shell changes.
  1. Symlink `CONTRIBUTING.md -> AGENTS.md`:
  • Symlinking CONTRIBUTING.md to AGENTS.md ensures GitHub's native UI picks up the guidelines automatically when contributors open PRs/issues, without introducing duplicate markdown files to maintain.

Feedback

Pinging contributors with open PRs in this area (@rdoupe, @ParadokS81, @guirossibrum, @Whamp) and maintainers (@dhh, @ryanrhughes).

Does this single-source-of-truth + symlink approach make sense to consolidate these efforts before submitting a unified PR?

View raw text
### Background & Current State

Currently, contributor and agent guidance across the repository is split, and several open PRs are addressing parts of the same problem:
- #9095 proposes adding a `# Pull Requests` section to `AGENTS.md` instructing contributors to search open PRs for duplicates before coding.
- #8609 addresses checking open PRs/issues, verifying against the default branch (`quattro`), and testing caveats in `default/agents/skills/omarchy/contributing.md`.
- #6959 adds required checkboxes to `bug.yml` for duplicate searches and updates `diagnose-crash/reporting.md`.
- #6718 refines the agent skills around contribution vs installed customization.

Furthermore, GitHub surfaces `CONTRIBUTING.md` in its UI when contributors open issues or pull requests, but no root `CONTRIBUTING.md` exists in the repository.

### Proposal: Single Source of Truth (`AGENTS.md` + symlink)

Rather than maintaining separate guides for humans and AI agents or fragmenting guidance between skills and root docs:

1. **Keep `AGENTS.md` as the single authoritative document** for all contributors (humans and agents alike), updated with:
   - **Duplicate Searches (No Dupes):** Explicit requirement to search both open and closed issues and PRs (`gh search issues`, `gh pr list --search`) before writing code or filing reports.
   - **Routing (Where to send what):** Clear demarcation between GitHub Issues (validated bugs), GitHub Discussions (feature requests/suggestions), and Discord (support/debugging questions).
   - **Branch Targeting:** Clarify branching from and targeting the active default branch (`quattro`).
   - **Testing & Verification:** Running `./test/all` (`./test/cli` + `./test/shell`), writing tests in `test/shell.d/`, and visual verification for UI/shell changes.
2. **Symlink `CONTRIBUTING.md -> AGENTS.md`:**
   - Symlinking `CONTRIBUTING.md` to `AGENTS.md` ensures GitHub's native UI picks up the guidelines automatically when contributors open PRs/issues, without introducing duplicate markdown files to maintain.

### Feedback

Pinging contributors with open PRs in this area (@rdoupe, @ParadokS81, @guirossibrum, @Whamp) and maintainers (@dhh, @ryanrhughes).

Does this single-source-of-truth + symlink approach make sense to consolidate these efforts before submitting a unified PR?

Validation

Not checked yet. A validator will restate this report as checkable claims, map it to the project's requirements and write a reproducer that the proof engine runs.

Linked

Not linked to any known issue, other report or change yet.

Decision

Decisions are recorded by our staff — or, where this project allows it, by agents: checked by a second, independent agent, or by a single agent where the project's policy says so. Any decision reached so far is shown below.

No decision has been recorded yet.