Ubisam-MobileGit/AGENTS.md

UBGitea Engineering Contract

This file is the canonical instruction source for every coding agent. If another agent-specific file conflicts with this file, this file wins.

Product

UBGitea is an Android client for the company Gitea instance.

• Gitea base URL: https://gitea.ubisampaju.synology.me
• OAuth client ID: 225589df-b992-4676-aae0-b2534ba7452d
• OAuth redirect URI: https://gitea.ubisampaju.synology.me/ubisampaju/oauth/callback
• Authentication: OAuth 2.0 Authorization Code with PKCE (S256)
• Client secret: never required, requested, stored, logged, or committed

Treat the base URL and client ID as configuration, even while they have production defaults.

Source of truth

Before work, read in this order:

1. AGENTS.md
2. The assigned file under tasks/
3. Relevant documents under docs/
4. Existing code and tests

Do not implement a feature without an acceptance-criteria task file. If requirements conflict or a security-sensitive choice is missing, stop and record the question rather than inventing behavior.

Agent roles

Codex — implementer and integrator

• Owns repository edits unless the task explicitly transfers ownership.
• Inspects existing code before changing it.
• Implements the smallest coherent change satisfying the task.
• Runs required checks and records evidence.
• Resolves review findings and keeps documentation synchronized.

Claude — independent reviewer and design critic

• Starts read-only unless explicitly assigned implementation ownership.
• Reviews requirements, architecture, security, UX, tests, and the current diff.
• Does not rewrite code while reviewing.
• Reports findings with severity, evidence, reproduction, and acceptance condition.
• May implement only after receiving a task that names its writable file scope.

Human product owner

• Decides product behavior, branding, external infrastructure, and release approval.
• Approves destructive operations and any change to OAuth or production configuration.

Single-writer protocol

• Only one agent may write a file during a task.
• Codex and Claude must not edit the same working tree concurrently.
• A handoff must identify task ID, current commit or diff, writable paths, completed checks, open findings, and next action.
• Never accept a review based only on “looks good.” Use acceptance criteria and test evidence.

Required work cycle

1. Restate the task outcome and risks.
2. Inspect relevant files and current git status.
3. Plan a small change with explicit file ownership.
4. Implement.
5. Run the checks listed in the task.
6. Review the diff against acceptance criteria.
7. Ask the independent reviewer to inspect it.
8. Resolve findings and rerun checks.
9. Update task evidence and hand off.

Android engineering rules

• Kotlin and Jetpack Compose are the default UI stack.
• Prefer unidirectional data flow and immutable UI state.
• Keep Android framework details at the edges of domain and data logic.
• Use coroutines with structured concurrency; do not use global scopes.
• Keep network DTOs separate from domain models.
• Never perform network or disk work on the main thread.
• All user-visible text belongs in string resources.
• Accessibility labels, loading, empty, offline, and error states are required.
• Avoid new dependencies unless the task explains why the standard stack is insufficient.

Security invariants

• Use the system browser for OAuth; do not use WebView for credential entry.
• Generate a fresh PKCE verifier, S256 challenge, and cryptographically random state per login attempt.
• Reject missing or mismatched state and unexpected redirect URIs.
• Never log authorization codes, access tokens, refresh tokens, cookies, or personal data.
• Store tokens using Android Keystore-backed protection.
• Do not disable TLS validation or add trust-all certificates.
• Do not place secrets in source, resources, Gradle properties, screenshots, fixtures, or CI logs.
• Destructive Gitea operations require explicit UI confirmation and dedicated task approval.

Verification gates

Before a task is complete, run all applicable checks:

• Gradle build
• Unit tests
• Android lint
• Static formatting/check task when configured
• Focused tests for changed behavior
• Secret scan or repository search for sensitive values
• Manual verification steps named by the task

If a check cannot run, record the exact reason and do not claim the task is complete.

Review severity

• P0: credential exposure, data loss, remote compromise, or release blocker
• P1: broken primary flow, authorization flaw, crash, or serious regression
• P2: incorrect edge case, maintainability problem, missing important test
• P3: minor quality or consistency improvement

Each finding must include file and line, concrete impact, evidence, and the condition that closes it.

Git discipline

• Preserve unrelated user changes.
• Keep commits focused on one task.
• Do not rewrite history, force-push, delete branches, or discard changes without approval.
• Do not commit generated build output, local SDK paths, signing keys, tokens, or secrets.
• Branch names should use codex/ for Codex-owned work and claude/ for Claude-owned work.

Definition of done

A task is done only when its acceptance criteria are met, required checks pass, no unresolved P0/P1 findings remain, documentation reflects material decisions, and a reviewer can reproduce the result from the recorded evidence.