chore: initialize AGENTS.md's

Author: skyline69

AGENTS.md

@@ -33,6 +33,87 @@ agcp status                 # Show proxy status
 agcp doctor                 # Diagnose configuration
 ```
 
+## Git Workflow
+
+### Commit Message Format
+
+Use Conventional Commits:
+
+```text
+<type>(<scope>): <summary>
+```
+
+- `type`: required
+- `scope`: optional but preferred (module/area like `tui`, `cloudcode`, `server`, `docs`)
+- `summary`: imperative mood, lower-case start, no trailing period, ideally <= 72 chars
+
+Examples:
+
+- `feat(tui): show popup when Gemini access is disabled`
+- `fix(cloudcode): map disabled-account 403 to clear error`
+- `docs(agents): add git workflow conventions`
+
+### Allowed Commit Types
+
+- `feat`: new user-facing behavior
+- `fix`: bug fix
+- `refactor`: internal code change without behavior change
+- `perf`: performance improvement
+- `test`: add or update tests
+- `docs`: documentation-only changes
+- `chore`: maintenance, tooling, cleanup
+- `ci`: CI pipeline/workflow changes
+- `build`: build system/dependency changes
+- `style`: formatting-only (no logic change)
+- `revert`: revert a prior commit
+
+For breaking changes, use `!`:
+
+- `feat(api)!: rename responses endpoint fields`
+
+And include a `BREAKING CHANGE:` footer in the commit body.
+
+### Branch Naming
+
+Use short descriptive names:
+
+- `feat/<short-topic>`
+- `fix/<short-topic>`
+- `chore/<short-topic>`
+- `docs/<short-topic>`
+
+Examples:
+
+- `feat/tui-runtime-warning-popup`
+- `fix/gemini-disabled-403-mapping`
+
+### Commit Hygiene
+
+- Keep one logical change per commit.
+- Run verification before commit:
+  - `cargo fmt`
+  - `cargo clippy -- -D warnings`
+  - `cargo test`
+- Do not commit secrets, tokens, local config, or logs.
+- Do not amend/rewrite history unless explicitly requested.
+
+### Pull Requests
+
+Use this PR structure:
+
+```markdown
+## Summary
+- What changed
+- Why it changed
+
+## Verification
+- cargo fmt
+- cargo clippy -- -D warnings
+- cargo test
+```
+
+Prefer small PRs with clear scope and explicit verification output.
+
 ## Architecture
 
 ```

src/AGENTS.md

@@ -0,0 +1,30 @@
+# AGENTS.md (src)
+
+Scope: applies to everything under `src/`.
+
+Start by reading the repository root `AGENTS.md`. This file adds source-tree specific rules.
+
+## Source Rules
+
+- Follow existing import order: `std` -> external crates -> `crate::*`.
+- Preserve existing error flow (`crate::error::{Error, Result}`) instead of ad-hoc error types.
+- Keep hot paths allocation-aware and prefer existing helpers/utilities.
+- Keep tracing structured (`request_id`, `model`, `status`, etc.) and avoid free-form log noise.
+- Any behavior change must include/adjust tests in the touched module.
+
+## Verification by Area
+
+- `src/server.rs` or request handlers changed:
+  - `cargo test server::tests --bin agcp`
+- `src/cloudcode/*` changed:
+  - `cargo test cloudcode:: --bin agcp`
+- `src/tui/*` changed:
+  - `cargo test tui::app::tests --bin agcp`
+- `src/format/*` changed:
+  - `cargo test format:: --bin agcp`
+
+Before final handoff, run:
+
+- `cargo fmt`
+- `cargo clippy -- -D warnings`
+- `cargo test`

src/cloudcode/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.md (src/cloudcode)
+
+Scope: applies to `src/cloudcode/`.
+
+Read `AGENTS.md` and `src/AGENTS.md` first.
+
+## Cloud Code Client Rules
+
+- Keep endpoint failover order stable unless explicitly required:
+  - `daily-cloudcode-pa.googleapis.com`
+  - `cloudcode-pa.googleapis.com`
+- Keep retry/backoff behavior coherent with existing constants and shared rate-limit helpers.
+- Avoid returning raw upstream provider payloads when a clear mapped error is possible.
+- New error mapping must include a regression test with representative upstream payload text.
+- Preserve request budget behavior (`MAX_WAIT_BEFORE_ERROR_MS`) and capacity retry limits.
+
+## Streaming / SSE
+
+- Keep SSE parser behavior compatible with existing event contracts.
+- Do not change event ordering or stop semantics without tests proving compatibility.
+
+## Required Checks for This Area
+
+- `cargo test cloudcode::client::tests --bin agcp`
+- `cargo test cloudcode::rate_limit::tests --bin agcp`
+- `cargo test cloudcode::sse::tests --bin agcp`

src/format/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.md (src/format)
+
+Scope: applies to `src/format/`.
+
+Read `AGENTS.md` and `src/AGENTS.md` first.
+
+## Conversion Rules
+
+- Keep Anthropic compatibility as the external contract.
+- When adding/changing fields, update both directions where relevant:
+  - `to_google.rs`
+  - `to_anthropic.rs`
+  - OpenAI/Responses adapters when impacted.
+- Do not silently drop meaningful fields without an explicit reason and tests.
+- Preserve stop reasons, usage accounting, and tool-call semantics.
+
+## Schema and Tooling Rules
+
+- Keep schema sanitation deterministic and minimal.
+- Preserve existing behavior for tool signatures and thinking blocks.
+
+## Required Checks for This Area
+
+- `cargo test format::to_google::tests --bin agcp`
+- `cargo test format::to_anthropic::tests --bin agcp`
+- `cargo test format::openai_convert::tests --bin agcp`

src/tui/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.md (src/tui)
+
+Scope: applies to `src/tui/`.
+
+Read `AGENTS.md` and `src/AGENTS.md` first.
+
+## TUI State and Rendering Rules
+
+- Keep app state transitions in `app.rs`; keep view modules render-focused.
+- For modal/popup UX:
+  - Add explicit `App` state.
+  - Block unrelated key handling while popup is visible.
+  - Support dismissal via `Enter` and `Esc`.
+- Maintain overlay precedence intentionally (help/popup/startup warnings ordering).
+- For log-driven warnings, normalize comparisons (case-insensitive) and test with realistic log lines.
+- Keep terminal-size handling and layout guards intact.
+
+## Interaction Rules
+
+- Mouse hit-testing should use cached rects already maintained in `App`.
+- Any new keyboard shortcut must not conflict with existing tab-local keybindings.
+
+## Required Checks for This Area
+
+- `cargo test tui::app::tests --bin agcp`
+- `cargo clippy -- -D warnings`