chore: update readme and agent instructions

[ovitrif]

Parent: #1113

Goal

Create one provider-neutral repository contract for contributors and AI agents, consolidate detailed guidance into generic shared rule surfaces, and expose a deterministic software-factory feedback loop through stable commands and documentation.

Instruction architecture

• AGENTS.md is the concise canonical entry point for every supported coding agent.
• CLAUDE.md, GEMINI.md, and WARP.md remain compatibility symlinks to AGENTS.md.
• .agents/commands/ is canonical; .claude/commands and .cursor/commands link to it.
• .ai/rules/android.md contains detailed shared Android/architecture/Compose/coroutine/logging/test rules.
• .ai/rules/verification.md contains verification routing, failure classification, runtime gates, and evidence-bearing closeout.
• .ai/rules/libraries.md contains reusable library guidance currently isolated in .cursor/notes/libs.md.
• .cursor/rules/ and .cursor/notes/ are removed after their valid unique content reaches shared surfaces.
• .github/copilot-instructions.md retains only Copilot review-specific deltas and agrees with the shared contract.
• README contains contributor-facing setup without choosing a default AI provider.

Deliverables

Reconcile and simplify rules

• Rename the AGENTS.md heading from CLAUDE.md to AGENTS.md and identify it as canonical.
• Remove the stale .cursor/default.rules.mdc reference.
• Reconcile current Cursor conflicts, including raw navigate vs navigateTo, runCatching vs cancellation-safe runSuspendCatching, preview patterns, logging ownership, and abstraction-by-line-count heuristics.
• Move durable detailed guidance into .ai/rules/android.md, .ai/rules/verification.md, and .ai/rules/libraries.md.
• Remove .cursor/rules/ and .cursor/notes/ after migration.
• Replace duplicate .cursor/commands/ files with a compatibility symlink to .agents/commands/.
• Reduce Copilot instructions to review-specific guidance consistent with canonical rules.
• Remove bullets absorbed by the execution contract so the result is shorter and easier to navigate.

Add the execution contract

Incorporate the planning-workflow and Karpathy/software-factory recommendations linked from the 30 Jul worklog:

• Add concise principles for explicit goals and assumptions, the smallest complete solution, surgical changes, and outcome verification.
• Use a consequential-ambiguity boundary: ask when the answer changes behavior, scope, architecture, authorization, or an irreversible outcome; otherwise apply the simplest repository-consistent interpretation.
• Add the autonomous loop: contract, inspect, implement, verify narrowly, classify failures, verify broadly, review the diff, repeat, and close out.
• Define evidence-bearing stop conditions.
• Add the durable planning loop: save the plan, open it with plannotator annotate, apply feedback to the same file, and continue until approval or closure without feedback.
• Define a risk-based, read-only independent verifier loop separate from the single mutating worktree owner.
• Define a closeout packet covering outcome, acceptance evidence, changed surface, automated/runtime checks, current head, unverified boundaries, and external gates.

Document stacked pull-request operations

• Document gh stack as the agent workflow for intentionally dependent, independently reviewable pull requests.
• Keep independent changes in independently mergeable pull requests.
• Order stack layers by dependency.
• Keep foundational changes on lower branches.
• Merge stacked pull requests from the bottom up.
• Keep staging and commits on standard git add and git commit.
• Document the non-interactive command surface:
  • Install with gh extension install github/gh-stack.
  • Initialize stacks with positional branch arguments to gh stack init.
  • Extend stacks with positional branch arguments to gh stack add.
  • Publish with gh stack submit --auto.
  • Inspect machine-readable state with gh stack view --json.
  • Rebase dependent layers after a lower-layer change with gh stack rebase --upstack.
• Set the target remote with --remote origin or remote.pushDefault so agent runs never open a remote picker.

Expose stable verification commands

• Add just verify for compile, unit tests, and detekt.
• Add just verify file <Test> for the targeted unit-test loop.
• Add just verify suite <Annotation> over existing generated instrumented lanes.
• Add non-mutating just doctor checks for Java, Android SDK/NDK, adb, Docker, connected target, and optional emulator prerequisites.
• Add just journey list and just journey <path> over repository XML journeys.
• Document the routing matrix for Kotlin logic, Compose rendering, storage/services, user flows, Rust/network boundaries, and build/workflow configuration.
• Exercise each command and provide actionable help when an optional dependency/device is unavailable.

Rewrite README AI guidance

• Consolidate the three Claude-focused areas into one AI agents section.
• Present AGENTS.md, .ai/rules/, and .agents/commands/ as the shared contract.
• Remove the README's default Claude recommendation, AI Code Review with Claude, Local Development Setup (YOLO Mode), and duplicate AI Dev Plugins sections.
• Keep provider integration assets in provider-specific directories while the generic README links only to shared surfaces.
• Remove Compose Stability Analyzer from recommended IDE plugins.
• Recommend Google's Android CLI for official documentation, SDK/emulator management, deployment, Android Studio tooling, UI inspection, screenshots, and Journeys.
• Link the official platform installation page and document:

brew tap android/tap
brew install android-cli
android update
android init

• Use android skills list to inspect installed skills.
• Present task-specific skill installation as an ordered workflow:
  1. Discover the applicable skill with android skills find "task keywords".
  2. Install it with android skills add --skill <skill-name>.
• Present android skills add --all as the explicit bulk-install option.
• State that supported coding agents automatically activate applicable installed skills.
• Explain that rerunning android skills add updates installed skills.
• Explain that customized skills require a distinct name.
• Document just verify, just doctor, and just journey.

Acceptance criteria

• AGENTS.md is the correctly titled canonical shared entry point.
• CLAUDE.md, GEMINI.md, and WARP.md resolve to AGENTS.md.
• .agents/commands/ is canonical; .claude/commands and .cursor/commands resolve to it.
• .ai/rules/android.md, .ai/rules/verification.md, and .ai/rules/libraries.md contain the migrated shared guidance.
• .cursor/rules/ and .cursor/notes/ no longer exist.
• Searches find no missing-rule reference or conflicting duplicate coding policy.
• Copilot review instructions agree with the shared contract.
• The concise execution, planning, verifier, and evidence-closeout contracts are present.
• Shared agent guidance defines when dependent work uses gh stack.
• Documented stack workflow keeps foundational changes below their dependents.
• Documented stack workflow merges pull requests from the bottom up.
• Documented gh stack commands run non-interactively.
• Documented stack operations select the intended remote without a picker.
• All new just commands behave as documented, including one representative journey.
• README has one provider-neutral AI agents section and no default Claude recommendation or duplicated setup/review section.
• README no longer recommends Compose Stability Analyzer.
• README documents current Android CLI commands from official Android sources.
• README presents android skills find followed by android skills add --skill <skill-name> as the task-specific workflow.
• README presents android skills add --all as the explicit bulk-install option.
• README states that supported coding agents automatically activate applicable installed skills.
• README explains how installed and customized skills are updated.
• A fresh contributor or agent can locate rules, install/update tooling, diagnose the environment, select verification, build/test, and run a journey.
• Markdown links, commands, and symlinks pass validation.
• just compile, just test, just lint, and just verify pass.

References

• Android CLI
• Android CLI installation
• Android skills
• GitHub stacked pull requests
• gh stack

[ovitrif]

Please include these details in the README guidance:

• Use android skills find followed by android skills add --skill <skill-name> as the task-specific skill path; keep android skills add --all as the explicit bulk-install option.
• State that supported coding agents automatically activate applicable installed skills.

These requirements complete the Android CLI and Android skills setup already specified in the issue body.