Repository documents
Start from the template. adl-desktop-app-template carries an example of every file on this page,
filled in for a placeholder app, ExampleApp. scripts/rename.sh <AppName> <package> renames it to yours.
Rules on this page 10
| ID | Level | Rule |
|---|---|---|
| REPO-01 | MUST | README.md is a landing page of about 200 lines: logo, badges, a one-paragraph pitch, the
hero screenshot, highlights, install, build, command line, config folder, license. Detail lives on the website.
|
| REPO-02 | MUST | CHANGELOG.md follows Keep a Changelog 1.1 and
SemVer: an ## [Unreleased] section with Added / Changed / Fixed / Removed, and each entry opens with a bold
one-line summary written for users.
|
| REPO-03 | MUST | LICENSE is MIT, “Copyright (c) 2026 Adrián Arturo De León Saldivar”.
|
| REPO-04 | MUST | NOTICE gives the app name, the copyright, “licensed under the MIT License”, then every
bundled third-party component with its license (Inter is OFL, AtlantaFX is MIT, OpenJFX is GPLv2+CPE…). It
ships inside the installers too.
|
| REPO-05 | MUST | AGENTS.md holds the operational rules for coding agents: essential commands,
worktree-per-task, the change checklist. It is not a changelog. A short CLAUDE.md points to it.
|
| REPO-06 | MUST | CONTRIBUTING.md says how to build, test, format, and open a PR.
|
| REPO-07 | MUST | docs/ holds architecture.md, conventions.md, testing.md, gotchas.md, release.md,
building-and-packaging.md and decisions/ (ADRs).
|
| REPO-08 | MAY | TODO.md holds the open list, kept in the same PR as the change.
|
| REPO-09 | MUST | .github/ISSUE_TEMPLATE/bug_report.yml is an issue form whose field ids (environment,
report) the in-app Report a Problem fills.
|
| REPO-10 | MUST | branding/ holds the source SVG of the icon. The PNG, ICNS and ICO generated from it sit
beside it or in packaging/.
|
- REPO-01 MUST
README.mdis a landing page of about 200 lines: logo, badges, a one-paragraph pitch, the hero screenshot, highlights, install, build, command line, config folder, license. Detail lives on the website.- Check (code):
README.mdis near 200 lines and has those parts, with links to the website for the rest. - Reference: Editora
README.md.
- Check (code):
- REPO-02 MUST
CHANGELOG.mdfollows Keep a Changelog 1.1 and SemVer: an## [Unreleased]section with Added / Changed / Fixed / Removed, and each entry opens with a bold one-line summary written for users.- Check (code): the file names Keep a Changelog and Semantic Versioning, starts with
## [Unreleased], and every entry starts with- **. - Reference: Editora
CHANGELOG.md.
- Check (code): the file names Keep a Changelog and Semantic Versioning, starts with
- REPO-03 MUST
LICENSEis MIT, “Copyright (c) 2026 Adrián Arturo De León Saldivar”.- Check (code):
LICENSEopens withMIT Licenseand that copyright line. - Reference: Editora
LICENSE.
- Check (code):
- REPO-04 MUST
NOTICEgives the app name, the copyright, “licensed under the MIT License”, then every bundled third-party component with its license (Inter is OFL, AtlantaFX is MIT, OpenJFX is GPLv2+CPE…). It ships inside the installers too.- Check (test): a test fails when a runtime dependency in
pom.xmlhas noNOTICEentry, and another whenLICENSEandNOTICEare not packaged. - Reference: Editora
NOTICE,NoticeCoverageTest,BuildHygieneTest.
- Check (test): a test fails when a runtime dependency in
- REPO-05 MUST
AGENTS.mdholds the operational rules for coding agents: essential commands, worktree-per-task, the change checklist. It is not a changelog. A shortCLAUDE.mdpoints to it. - REPO-06 MUST
CONTRIBUTING.mdsays how to build, test, format, and open a PR.- Check (code):
CONTRIBUTING.mdnames the build, test and format commands and the PR step. - Reference: Editora
CONTRIBUTING.md.
- Check (code):
- REPO-07 MUST
docs/holdsarchitecture.md,conventions.md,testing.md,gotchas.md,release.md,building-and-packaging.mdanddecisions/(ADRs).- Check (code): each of those paths exists under
docs/. - Reference: Editora
docs/.
- Check (code): each of those paths exists under
- REPO-08 MAY
TODO.mdholds the open list, kept in the same PR as the change.- Check (code):
TODO.mdexists at the root. - Reference: Editora
TODO.md.
- Check (code):
- REPO-09 MUST
.github/ISSUE_TEMPLATE/bug_report.ymlis an issue form whose field ids (environment,report) the in-app Report a Problem fills.- Check (code): the form has fields with
id: environmentandid: report. - Reference: Editora
.github/ISSUE_TEMPLATE/bug_report.yml.
- Check (code): the form has fields with
- REPO-10 MUST
branding/holds the source SVG of the icon. The PNG, ICNS and ICO generated from it sit beside it or inpackaging/.- Check (code):
branding/has an.svg; thejpackageicon paths inpom.xmlpoint at the generated files. - Reference: Editora
branding/editora-icon.svg, witheditora.png,.icnsand.icobeside it; the template keeps them inpackaging/icons/.
- Check (code):

README badges (in this order)
Section titled “README badges (in this order)”[](…/actions/workflows/ci.yml)[](…/releases/latest)[](LICENSE)[](<homepage>/docs/pauta/)[](…/stargazers)
The Pauta badge names the edition and the conformance, in green 2ea043 for Complete, blue 5b8def for Core and
amber d29922 for Partial (where it reads “Working toward”), and links to the app’s Pauta conformance docs page; a test holds
it to pauta.version and the computed conformance (Conformance).
The hero screenshot is a <picture> with a dark srcset under prefers-color-scheme: dark, so GitHub
shows the screenshot that matches the reader’s theme. Screenshots are taken at 2× by a headless harness so
they can be retaken after any UI change. The README states that the app is built with the help of AI
coding tools.
Pauta 4.3.0 · · Changelog · This page in the latest edition