Document developer workflow conventions

AGENTS.md

@@ -17,10 +17,59 @@ working inside those directories.
 - Use the `git-safe-workflow` skill for commits and PRs.
 - Default path is branch -> local checks -> exact-file commit -> PR.
 - Do not push directly to `main` unless the user explicitly asks for direct-main
-  behavior.
+  behavior in that specific request. A prior approval to push does not carry
+  forward to later sessions or later commits — ask again each time.
 - Do not merge PRs, close issues, post public GitHub comments, tag, or release
   without a separate explicit user request.
 
+## Developer Workflow Conventions
+
+Derived from this repo's actual commit/PR history (`git log`, `gh pr list`),
+not just the templates. Follow the observed pattern, not an invented one.
+
+**Branch naming** — prefix by session origin, then a kebab-case topic slug:
+- `codex/<topic-slug>` — dominant pattern for Codex CLI sessions (e.g.
+  `codex/control-plane-operator-gates`, `codex/thermonuclear-fixes`).
+- `claude/<topic-slug>` — use this for Claude Code sessions; no Claude-specific
+  prefix existed before, this mirrors the established `codex/` convention so
+  branch origin stays identifiable.
+- `docs/issue-<n>-<topic-slug>` — docs-only PRs that close a numbered issue.
+
+**Commit messages** — single-line, capitalized, imperative, verb-first summary
+(`Harden Telegram MCP control surfaces`, `Add Telegram metadata fast lane`).
+No conventional-commit type prefix is required or consistently used — only
+2 of the last 24 commits use one (`Chore: ...`, `docs: ...`), so don't invent
+a strict `feat:`/`fix:` scheme. For multi-part changes, add a body with `-`
+bullets (mirrors what a squashed PR's `## Summary` becomes). Squash-merged PRs
+get GitHub's `(#<n>)` suffix automatically — don't add it by hand on direct
+commits.
+
+**Attribution** — 22 of the last 24 commits in this repo carry no co-author
+trailer at all; this repo has not historically used `Co-Authored-By`. Claude
+Code's own default behavior appends a `Co-Authored-By: Claude ... <noreply@anthropic.com>`
+trailer on commits it authors — keep doing that for Claude-authored commits
+(it accurately discloses tooling and costs nothing), but don't backfill it
+onto older Codex-authored history or expect it there.
+
+**PR body structure** — two header variants appear, use this shape:
+```
+## Summary
+- one bullet per change
+
+## Verification
+- exact command(s) run
+- actual result, not "tests pass" (e.g. "control-plane 204 passed, MCP 337 tests OK")
+```
+Add an optional `## GitHub context` section when the PR interacts with CI
+state or another open PR (see PR #13). This should satisfy
+`.github/PULL_REQUEST_TEMPLATE.md`'s checklist directly — fill it in, don't
+leave it as unchecked boilerplate.
+
+**Test plan / evidence** — run `scripts/safe-gate` before every non-trivial
+commit (see Local Gate below); quote real test counts in the PR, not vague
+claims. For live-behavior changes, also run local live smoke and paste
+redacted output per `CONTRIBUTING.md`.
+
 ## Local Gate
 
 Run `scripts/safe-gate` before committing non-trivial changes. It checks:

CLAUDE.md

@@ -0,0 +1,46 @@
+# Claude Code Notes
+
+Canonical behavior contract for this repo is [`AGENTS.md`](AGENTS.md) — read
+it first. This file adds Claude-specific context so a session that only
+loads `CLAUDE.md` still has the essentials.
+
+## Language
+Respond in Russian. Code, git commit messages, and CLI output stay in English.
+
+## Scope
+Three coupled surfaces — prefer the more specific `mcp/AGENTS.md` /
+`mcp/CLAUDE.md` and `control-plane/AGENTS.md` when working inside those
+directories:
+- `mcp/` — Telegram MCP server and live tool behavior.
+- `control-plane/` — local operator commands, release checks, agent docs.
+- `plugin/` — packaged Codex plugin and bundled Telegram skill.
+
+## Developer Workflow (summary — see `AGENTS.md` for the full derivation)
+
+- **Branch**: `claude/<topic-slug>` for work you start (mirrors the repo's
+  established `codex/<topic-slug>` convention; do not invent another prefix).
+- **Commit message**: single-line, capitalized, imperative summary
+  (`Add X`, `Harden Y`) — no type prefix required; this repo doesn't use
+  conventional commits consistently. Bullet body only for multi-part changes.
+- **Attribution**: this repo's own history carries no `Co-Authored-By`
+  trailers, but keep Claude Code's default trailer on commits you author —
+  it's accurate disclosure, just don't backfill it onto older commits.
+- **PR body**: `## Summary` (bullets) + `## Verification` (exact commands and
+  real output, not "tests pass") + optional `## GitHub context`.
+- **Before committing anything non-trivial**: run `scripts/safe-gate`. Quote
+  its actual output in the PR, don't paraphrase.
+- **main**: default path is branch -> PR, never push directly to `main`
+  unless the user explicitly asks for that in the current request — an
+  earlier approval to push doesn't carry forward.
+
+## Commands
+
+- `./scripts/safe-gate` — MCP tests + control-plane tests (portable mode) +
+  agent docs sync drift + whitespace hygiene. Run before every non-trivial
+  commit.
+- `./scripts/ci-release-gate.sh` — full release verification.
+- `PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -p 'test_*.py'`
+  — run from `mcp/` directly when iterating on that surface. Zero extra deps.
+  `CONTRIBUTING.md` shows `pytest` instead — that also works, but `pytest`
+  isn't a declared dependency, so a fresh `.venv` needs
+  `uv pip install pytest` before `uv run pytest` will find it.