ADFA-4357 Add agent & contributor documentation set - #1422
Merged
Conversation
Add a coordinated set of Markdown docs to onboard both human and AI contributors and to capture the project's architectural decisions. - CLAUDE.md: operational guide for Claude Code (build/test commands, ABI flavors, project constraints); points to ARCHITECTURE.md for architecture rather than duplicating it. - AGENTS.md: operational rules for agents (CI-vs-local, Jira CLI, SonarQube MCP, git message handling); persistence rule now points to ARCHITECTURE.md. - ARCHITECTURE.md: single source of truth for module layout, layering & data flow (UDF), dependency rules, tech stack, state management, and the testing strategy. - REVIEW.md: code-review coaching (exception handling vs the Sentry crash wrapper, LeakCanary leaks, StrictMode, OWASP, tests/coverage, analytics, duplication, docstrings, strings.xml). - SECURITY.md: how to avoid introducing new SonarQube/Snyk/Semgrep blocker findings; vulnerability classes for an Android/Kotlin IDE. - docs/adr/: 8 Architecture Decision Records (MADR/Nygard) plus an index covering persistence-without-Room, on-device builds via the Gradle Tooling API, the vendored toolchain, embedded Termux, per-ABI flavors, Koin DI, the StrictMode whitelist engine, and retaining the com.itsaky.androidide namespace.
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds repository-wide documentation for operating rules, architecture conventions, review standards, security guidance, and ADRs covering persistence, build, runtime, DI, flavors, StrictMode, namespace retention, and Compose. ChangesProject Documentation Suite
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/adr/0005-per-abi-product-flavors.md (1)
39-39:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winTrailing artifact at end of file.
Line 39 contains a stray
39character that appears to be a formatting artifact or incomplete truncation.Verify the file ends cleanly. If this is the intended end, remove the stray character.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/adr/0005-per-abi-product-flavors.md` at line 39, The file docs/adr/0005-per-abi-product-flavors.md has a stray character "39" at the end that appears to be a formatting artifact. Locate the end of the file and remove this trailing character to ensure the markdown file ends cleanly without any extraneous content.
🧹 Nitpick comments (2)
REVIEW.md (1)
80-80: 💤 Low valueMinor: replace "exactly" with more specific verb.
LanguageTool flags "exactly" as an over-used intensifier. Consider "are" or "represent" depending on intended emphasis, or rephrase to avoid the intensifier.
Example:
-- **No duplication.** If you copy-pasted a block, extract a function/extension into the right `common`/`utils` module. Before adding a helper, grep — we likely already have it. Repeated literals/magic numbers → named constants. +- **No duplication.** If you copy-pasted a block, extract a function/extension into the right `common`/`utils` module. Before adding a helper, grep — we likely already have it. Repeated literals/magic numbers become named constants.Alternatively, keep the intensity but rephrase: "those are the error paths the crash wrapper would otherwise catch" → "those represent the error paths the crash wrapper would otherwise catch".
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@REVIEW.md` at line 80, In the REVIEW.md file, locate the sentence containing "those are exactly what the crash wrapper would otherwise catch in production" and remove the over-used intensifier "exactly" by replacing it with a more specific verb such as "represent" or rephrase the sentence to eliminate the intensifier entirely (for example, change "those are exactly what" to "those represent what" or similar phrasing that conveys the same meaning without the weak intensifier).docs/adr/0005-per-abi-product-flavors.md (1)
9-9: 💤 Low valueMinor: replace "very large" with a stronger adjective for clarity.
LanguageTool flags "very large" as an over-used intensifier. Consider "substantial", "sizable", or "prohibitive" depending on emphasis.
Example:
-Code On The Go is distributed primarily as a **direct APK download** from the App Dev for All website, not exclusively through Google Play, so we cannot rely on Play's automatic per-ABI splitting to slim downloads. +Code On The Go is distributed primarily as a **direct APK download** from the App Dev for All website, not exclusively through Google Play, so we cannot rely on Play's automatic per-ABI splitting to slim substantial downloads.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/adr/0005-per-abi-product-flavors.md` at line 9, In the file docs/adr/0005-per-abi-product-flavors.md, replace the phrase "very large" with a stronger, more specific adjective in the sentence describing universal APK size. Consider using alternatives such as "substantial", "sizable", or "prohibitive" to provide clearer emphasis on why per-ABI splitting is necessary, as "very large" is flagged as an over-used intensifier. Choose the adjective that best conveys the intended severity of the size concern in the context of direct APK distribution.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@docs/adr/0005-per-abi-product-flavors.md`:
- Line 39: The file docs/adr/0005-per-abi-product-flavors.md has a stray
character "39" at the end that appears to be a formatting artifact. Locate the
end of the file and remove this trailing character to ensure the markdown file
ends cleanly without any extraneous content.
---
Nitpick comments:
In `@docs/adr/0005-per-abi-product-flavors.md`:
- Line 9: In the file docs/adr/0005-per-abi-product-flavors.md, replace the
phrase "very large" with a stronger, more specific adjective in the sentence
describing universal APK size. Consider using alternatives such as
"substantial", "sizable", or "prohibitive" to provide clearer emphasis on why
per-ABI splitting is necessary, as "very large" is flagged as an over-used
intensifier. Choose the adjective that best conveys the intended severity of the
size concern in the context of direct APK distribution.
In `@REVIEW.md`:
- Line 80: In the REVIEW.md file, locate the sentence containing "those are
exactly what the crash wrapper would otherwise catch in production" and remove
the over-used intensifier "exactly" by replacing it with a more specific verb
such as "represent" or rephrase the sentence to eliminate the intensifier
entirely (for example, change "those are exactly what" to "those represent what"
or similar phrasing that conveys the same meaning without the weak intensifier).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 636711f5-1206-408a-9727-feafce7276a9
📒 Files selected for processing (14)
AGENTS.mdARCHITECTURE.mdCLAUDE.mdREVIEW.mdSECURITY.mddocs/adr/0001-persistence-without-room.mddocs/adr/0002-on-device-builds-via-gradle-tooling-api.mddocs/adr/0003-vendored-forked-desktop-toolchain.mddocs/adr/0004-embedded-termux-runtime.mddocs/adr/0005-per-abi-product-flavors.mddocs/adr/0006-koin-dependency-injection.mddocs/adr/0007-strictmode-whitelist-engine.mddocs/adr/0008-retain-androidide-namespace.mddocs/adr/README.md
Promote accessibility from a proposed item to an enforced review section and add a parallel contextual-help (long-press 3-tier) rule, both keyed to existing patterns (ADFA-2667 screen-reader work, the idetooltips module). - REVIEW.md: new sections for content-description coverage and long-press help; matching 60-second-checklist entries; renumber trailing sections. - idetooltips/README.md: state the long-press-for-help-everywhere principle and the three-tier (tooltip / tooltip / web page) help model.
hal-eisen-adfa
marked this pull request as draft
June 19, 2026 03:37
- ADR 0009: new IDE UI is Jetpack Compose, no new XML View screens; the UDF/Koin/StateFlow stack is unchanged. Indexed in docs/adr/README.md. - ARCHITECTURE.md: tech-stack UI row + overview now point to ADR 0009 instead of claiming the IDE is 'Not Compose'. - REVIEW.md: new Compose-only rule in Architecture alignment; accessibility (§8) now gives View + Compose forms for each rule (semantics, clearAndSetSemantics, the HardcodedText lint gap); contextual help (§9) notes idetooltips has no Compose entry point yet (displayTooltipOnLongPress is View-based); promote Offline-first from proposed to an accepted section.
…idge The Compose-only mandate (ADR 0009) and the long-press-everywhere rule (REVIEW.md section 9) need a Compose entry point into the View-based idetooltips system, which does not exist yet. Reference the follow-up ticket from both docs so the gap is tracked, not forgotten. Docs only.
…4382 The README's usage examples document a showIDETooltip() API that no longer exists (real API: TooltipManager.showTooltip / displayTooltipOnLongPress) and claim a Room store the module doesn't use (it's raw SQLite). Add a banner so contributors trust the code until the refresh lands. Docs only.
Leave idetooltips/README.md untouched on this PR. Removes both the design-principle section and the staleness banner added earlier; the README refresh is handled wholesale in ADFA-4382 instead.
- REVIEW.md: new Code-quality rule + 60-second-checklist entry requiring a change to update any module README/ARCHITECTURE.md/ADR it affects, or leave a tracked note. - AGENTS.md: one-line operational pointer to the REVIEW.md rule, so agents that read AGENTS.md (but not REVIEW.md) still apply it.
Tighten prose across CLAUDE.md, AGENTS.md, ARCHITECTURE.md, REVIEW.md, and the ADRs — cut hedging, doubled phrasings, and restated context; no facts, paths, commands, or decisions changed. Also: - REVIEW.md §9: drop the stale showIDETooltip reference in the intro. - ARCHITECTURE.md: reconcile the data-flow UI note with ADR 0009 (existing UI is Views; new UI is Compose) instead of a flat 'not Compose'.
- Experimental feature flag: clarify it's a user-facing early-access opt-in (singular flag), not a kill switch for us to disable features in the field. - Remove the performance-budget proposal; captured as ADFA-4383 instead.
Move it out of 'Open for discussion' into a numbered review section; gate not-yet-stable features behind the user-facing early-access flag. Renumber PR hygiene to §13.
…scussion section The MIN_SDK guard concern doesn't arise in practice; remove the item. It was the last proposal, so remove the empty section scaffolding too. REVIEW.md now ends at §13 PR hygiene.
hal-eisen-adfa
marked this pull request as ready for review
June 19, 2026 06:57
itsaky-adfa
requested changes
Jun 23, 2026
jatezzz
previously requested changes
Jun 24, 2026
Daniel-ADFA
reviewed
Jun 29, 2026
fryanpan
reviewed
Jun 30, 2026
fryanpan
reviewed
Jun 30, 2026
fryanpan
reviewed
Jun 30, 2026
fryanpan
reviewed
Jun 30, 2026
fryanpan
reviewed
Jun 30, 2026
fryanpan
reviewed
Jun 30, 2026
fryanpan
reviewed
Jun 30, 2026
fryanpan
reviewed
Jun 30, 2026
… exceptions Reframes ADR 0001 and cascades to ARCHITECTURE.md, AGENTS.md, REVIEW.md per review feedback from itsaky-adfa and dara-abijo-adfa. Room is the default; raw SQLite is reserved for prebuilt read-only DBs, performance/allocation- critical indexing, and cross-boundary schemas. Recent Projects is the reference example of the default, not an exception. Renames 0001-persistence-without-room.md -> 0001-prefer-room-for-persistence.md.
…ing API Rewrites ADR 0003 per itsaky-adfa's correction (confirmed against the code): composite-build/build-deps* modules ship in the APK and run at IDE runtime (e.g. Java LSP via javac/jdk-compiler/jdt), and live in composite builds for build-time caching. Adds an explicit callout that the Gradle Tooling API is a separate out-of-process JDK from terminal bootstrap packages, driven over JSON-RPC. Fixes two cross-reference lines in ADR 0002 that conflated the two.
Per jatezzz's review: Claude Code auto-reads CLAUDE.md, so a separate AGENTS.md forces a secondary read and risks the operational rules being skipped. Folds all unique AGENTS.md content into CLAUDE.md (emulator/device, Jira CLI, SonarQube MCP, CI-job resolution, official-actions-in-CI, git/gh messaging, keep-docs-current, brevity) and replaces AGENTS.md with a thin pointer so the cross-tool AGENTS.md convention still resolves without duplicated, drift-prone content. Repoints the AGENTS.md citations in REVIEW.md and SECURITY.md to CLAUDE.md.
…arcelize, namespace) Verified each against the code before editing: - Code style: tabs + LF via Spotless (leadingSpacesToTabs), not 2-space; and the right formatters (Java=Eclipse config, Kotlin/Gradle=ktlint, XML=Eclipse WTP), not ktfmt/google-java-format/Android Studio. Fixed CLAUDE.md and REVIEW.md. - State management: require sealed types for mutually-exclusive UI states (no boolean hell); reframed the example to lead with real sealed CloneRepoUiState and caption the PluginManagerUiState boolean example as independent-fields-only. - Added a Parceling row: use @parcelize, never hand-roll Parcelable. - REVIEW.md: strings live in the :resources module's strings.xml. - Emulator: app is arm-only (v7/v8, no x86), so a physical arm device is often needed; an x86_64 emulator can't run it. - ADR 0008: the decisive reason to keep the namespace is the terminal bootstrap packages coupling — a rename must be an atomic big-bang change across both.
- PR sizing (fryanpan): prefer one PR per ticket/use case, break large work into reviewable commits (mechanical vs. behavioral) with review-by-commit; ~500 LOC/10 files is a soft signal, not a hard cap. (CLAUDE.md, REVIEW.md) - ADR status (dara-abijo-adfa): all 9 ADRs + README index Accepted -> Proposed; they ratify to Accepted when this PR merges. - Nits (CodeRabbit): ADR 0005 'very large' -> 'prohibitively large'; REVIEW.md drop the 'exactly' intensifier. (The stray '39' char was already absent.)
- New docs/plugin-api.md (Daniel-ADFA): maintainer-facing plugin API stability & compatibility guide. Defines the contract surface (:plugin-api interfaces/data classes/enums + manifest keys, permission strings, formats), the current policy (API not frozen, backward/binary compat not yet guaranteed but changes must be deliberate/documented/justified), the Kotlin binary-compat traps, a pre-change checklist, and a follow-up to add binary-compat tooling. Grounded in the plugin dev guide and the real :plugin-api module. - REVIEW.md 13 (fryanpan): replaced the vague 'consider impact on plugins' with a concrete check — does it touch the API surface, is any break deliberate and documented, and a mechanical impact check against the in-tree example plugins (apk-viewer / markdown-preview / keystore-generator) and the plugin-examples repo. - Fixed the plugin.json manifest claim -> AndroidManifest.xml <meta-data> in ARCHITECTURE.md and REVIEW.md (meta-data is the primary loader path).
Commits the in-repo author-facing plugin guide (project layout, AndroidManifest meta-data contract, theme-aware icons, building/installing, troubleshooting) and wires reciprocal links between it (how to author) and plugin-api.md (how to evolve the API).
- Per-item evidence ledger: a review must show what it checked and the result, proportional to change size (not bare LGTM). - Feature completeness: start from the Jira ticket; confirm requirements are implemented and the intended flow is tested. Added as lead rule + checklist item. - Coverage target: >=50% line & branch on new non-UI code (rising over time), proven via jacocoAggregateReport; UI exempt. - Architecture (10): inlined the key rules as a checklist (UDF, sealed state, Koin, Room, module dependency direction, Compose, system bars) so reviewers don't have to follow links; noted an architecture-review skill as follow-up. - Threading (3): long-running CPU work off the main thread (JSON decode crash). - Duplication (7): broadened to reimplemented logic / cross-subagent duplication. - Offline (11) and leaks (2): concrete verification steps (adb network off; a clean LeakCanary run) recorded as evidence. - CLAUDE.md: post in-progress ticket updates via the jira CLI. - SECURITY.md: relationship to Claude's /security-review (complements the three CI scanners, doesn't replace the enforced baseline).
…NTRIBUTING.md - CLAUDE.md: new Branch model section — main is release-only (merges from stage), stage is the protected default/integration branch and the base for feature branches, feature branches PR back into stage. Never target main directly. - CONTRIBUTING.md: replaced the stale 'dev branch is protected' line (there is no dev branch; stage is the protected default, main is not) with the correct branch model, and corrected the Source code format section (ktfmt/google-java-format/ 2-space -> Spotless: tabs, ktlint for Kotlin, Eclipse for Java/XML). Edits deliberately avoid the CONTRIBUTING.md regions changed by PR 1478 (community-contribution branch naming) to prevent merge conflicts.
Collaborator
Author
|
Thanks everyone — great round of feedback. Pushed 9 commits addressing all of it, and replied inline on each thread. Summary:
Two things worth a look from the team:
Re-requesting review from @itsaky-adfa, @jatezzz, @dara-abijo-adfa. |
A project skill that forces a read of ARCHITECTURE.md + the ADRs, then checks a diff against the documented patterns (UDF/state, Koin, Room-vs-SQLite, Compose, module boundaries, ABI flavors, dependency substitution, @parcelize, strings), tracing each finding to its ADR/section. Addresses the 'rules in on-demand docs get missed' problem: the skill guarantees the authoritative docs are read at review time rather than relying on prose links. REVIEW.md §10 now points to it. Commits only the skill file under .claude/ (not local settings or hooks).
A non-blocking pre-push hook (.githooks/pre-push/0002-architecture-review-nudge) that reminds the author to run an architecture pass when a push touches first-party Kotlin/Java. It always exits 0 (never gates), and stays silent unless production app source changed — docs/test/vendored-only pushes produce no output. Points at the architecture-review skill and REVIEW.md section 10. Runs via the existing .githooks dispatcher after 0001-run-spotless.
Signed-off-by: Akash Yadav <akashyadav@appdevforall.org>
Signed-off-by: Akash Yadav <akashyadav@appdevforall.org>
Signed-off-by: Akash Yadav <akashyadav@appdevforall.org>
Signed-off-by: Akash Yadav <akashyadav@appdevforall.org>
Signed-off-by: Akash Yadav <akashyadav@appdevforall.org>
itsaky-adfa
approved these changes
Jul 13, 2026
hal-eisen-adfa
dismissed stale reviews from dara-abijo-adfa and jatezzz
July 14, 2026 00:03
Addressed, thanks
This was referenced Aug 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
ADFA-4357 — Agent & contributor documentation set
Adds a coordinated set of Markdown docs to onboard both human and AI contributors and to record the project's architectural decisions. Docs only — no code or build changes.
What's included
CLAUDE.mdARCHITECTURE.mdfor architecture.AGENTS.mdARCHITECTURE.mdREVIEW.mdstrings.xml.SECURITY.mddocs/adr/ADRs
com.itsaky.androididenamespace after rebrandNotes for reviewers
Content was written against the actual codebase (verified patterns: Koin DI, Firebase
IAnalyticsManager, the StrictMode whitelist engine, Sentry global handler,tooling-apiout-of-process, vendored toolchain). Two claims are author inferences worth a sanity check:ARCHITECTURE.md/SECURITY.md: "Retrofit is in the catalog but effectively unused in app code."Follow-ups (intentionally out of scope)
idetooltips(surfaced by ADR 0001/0003).ARCHITECTURE.mdtodocs/adr/.