docs(agents): add git branching workflow and ASC session plan

.agents/AGENTS.md

@@ -68,6 +68,24 @@ stale `AuthKey_<id>.p8` and fail with a 401, and `--auth-string` would put
 the key in the process table. Upload is CLI-only, because a tool call that
 blocks for minutes and publishes a build doesn't belong in MCP.
 
+## Git branching workflow
+
+Branches flow in one direction: `main` ← `development` ← feature branch.
+
+- `main` is the release branch. Never commit to it directly; it only advances
+  by merging `development`.
+- `development` is the integration/base branch. Never commit to it directly
+  either — every change lands through a pull request.
+- Do the work on a short-lived **feature branch** cut from `development`
+  (`feat/…`, `fix/…`, `docs/…`), then **open a PR into `development`**. Let CI
+  (fmt / clippy `-D warnings` / test / doc / lower-crate solo builds) pass
+  before merge.
+- When `development` is ready to release, it is merged into `main` via its own
+  PR — not by pushing commits onto `main`.
+
+So: branch off `development`, push the feature branch, open a PR → `development`.
+Do not commit straight to `development` or `main`.
+
 ## Verify before committing
 
 CI (`.github/workflows/ci.yml`, ubuntu + macOS) runs these, and warnings are

.agents/plans/from-splitfire-ai-apps-session.md

@@ -0,0 +1,58 @@
+# Findings — SplitFire AI apps release session (KaroKowe Jam TestFlight)
+
+Context: shipping a macOS build (KaroKowe Jam) to TestFlight via the `asc`
+CLI. Concrete app id / bundle id / build number are omitted — this is a public
+repo; keep plan files to generalizable `asc` findings, not per-app identifiers.
+
+## 1. The release `asc` binary can silently lag `development`
+
+The installed/release `asc` predated the `testflight` subcommand, yet
+`asc apps upload` still worked — because upload only shells out to `altool`
+and doesn't touch the newer code paths. So an upload succeeding is **not**
+evidence that the binary is current.
+
+**Rule:** before relying on a newly-added subcommand (e.g. `testflight`),
+rebuild `asc` from `development` first (`cargo build --release`), or you'll hit
+`unrecognized subcommand` on a binary that otherwise looks healthy.
+
+## 2. `testflight groups` takes a nested subcommand, not an app id
+
+`asc testflight groups <APP_ID>` fails with
+`error: unrecognized subcommand '<APP_ID>'`. The app id is an argument of the
+leaf command, not of `groups`. Confirmed command surface:
+
+```
+asc testflight groups list <APP_ID>
+asc testflight groups get <GROUP_ID>
+asc testflight groups add-build --build-id <BUILD_ID>... <GROUP_ID>
+
+asc testflight app-review-detail get <APP_ID>
+asc testflight app-review-detail update ...        # contact + demo-account details
+
+asc testflight app-review-submissions list <BUILD_ID>
+asc testflight app-review-submissions submit <BUILD_ID>
+```
+
+Notes:
+- `groups add-build` and `app-review-submissions submit` are **CLI-only** by
+  design (adding a build to an external group / submitting to Beta App Review
+  can trigger review — not something an MCP tool call should do unattended).
+- Both support `--dry-run` to print the request body before writing.
+
+## 3. Finish-the-release recipe (for next time)
+
+1. Upload: `asc apps upload <PKG> --wait` (always `--p8-file-path`; never the
+   script's raw `altool`, which can pick a stale `AuthKey_<id>.p8` → 401).
+2. Poll to VALID: `asc apps builds <APP_ID> --version <BUILD_NUMBER>` → grab the
+   build id once `processingState` is VALID.
+3. Beta review contact details: `asc testflight app-review-detail update ...`.
+4. Submit: find the Public Link group via `asc testflight groups list <APP_ID>`,
+   then either `groups add-build --build-id <BUILD_ID> <GROUP_ID>` or
+   `app-review-submissions submit <BUILD_ID>`.
+
+## 4. Process note
+
+Plan files and any other changes land on a feature branch and go in through a
+PR — never a direct commit to `development` (or `main`). It's easy to slip when
+a change feels like "just docs"; treat the branching rule as unconditional.
+See the **Git branching workflow** section of `AGENTS.md`.