From 8f98be36b307c6dac7d2334000891165645e54cf Mon Sep 17 00:00:00 2001 From: Seto Elkahfi <1797197+setoelkahfi@users.noreply.github.com> Date: Mon, 12 Oct 2026 00:14:47 +0200 Subject: [PATCH 1/2] docs(agents): add git branching workflow and ASC session plan Document the main <- development <- feature-branch policy (one direction, all changes via PR, never direct commits to main or development) in the canonical agent doc, and record the generalizable findings from an App Store Connect session as a plan. Co-Authored-By: siGit Code v1.6.7-acp --- .agents/AGENTS.md | 18 ++++++ .../plans/from-splitfire-ai-apps-session.md | 57 +++++++++++++++++++ 2 files changed, 75 insertions(+) create mode 100644 .agents/plans/from-splitfire-ai-apps-session.md diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md index e97fab9..7ca0037 100644 --- a/.agents/AGENTS.md +++ b/.agents/AGENTS.md @@ -68,6 +68,24 @@ stale `AuthKey_.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 diff --git a/.agents/plans/from-splitfire-ai-apps-session.md b/.agents/plans/from-splitfire-ai-apps-session.md new file mode 100644 index 0000000..36c52db --- /dev/null +++ b/.agents/plans/from-splitfire-ai-apps-session.md @@ -0,0 +1,57 @@ +# 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 ` fails with +`error: unrecognized subcommand ''`. The app id is an argument of the +leaf command, not of `groups`. Confirmed command surface: + +``` +asc testflight groups list +asc testflight groups get +asc testflight groups add-build --build-id ... + +asc testflight app-review-detail get +asc testflight app-review-detail update ... # contact + demo-account details + +asc testflight app-review-submissions list +asc testflight app-review-submissions submit +``` + +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 --wait` (always `--p8-file-path`; never the + script's raw `altool`, which can pick a stale `AuthKey_.p8` → 401). +2. Poll to VALID: `asc apps builds --version ` → 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 `, + then either `groups add-build --build-id ` or + `app-review-submissions submit `. + +## 4. Process note + +PR #29 was committed directly on `development`, which violates the standing rule +(never commit directly to `development` in smbcloud-ascapi — branch + PR). +Decide: rewrite onto a feature branch, or leave. From 52bd6d4bdcd00baf2d7254e4aecf143fdc872d26 Mon Sep 17 00:00:00 2001 From: Seto Elkahfi <1797197+setoelkahfi@users.noreply.github.com> Date: Mon, 12 Oct 2026 00:19:44 +0200 Subject: [PATCH 2/2] docs(agents): genericize plan-file process note Drop the specific PR reference and 'we slipped' framing from the ASC session plan; keep the generalizable lesson (plan files land via a feature branch + PR, never a direct commit to development/main) and point at the Git branching workflow section of AGENTS.md. Co-Authored-By: siGit Code v1.6.7-acp --- .agents/plans/from-splitfire-ai-apps-session.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.agents/plans/from-splitfire-ai-apps-session.md b/.agents/plans/from-splitfire-ai-apps-session.md index 36c52db..f6a5ce1 100644 --- a/.agents/plans/from-splitfire-ai-apps-session.md +++ b/.agents/plans/from-splitfire-ai-apps-session.md @@ -52,6 +52,7 @@ Notes: ## 4. Process note -PR #29 was committed directly on `development`, which violates the standing rule -(never commit directly to `development` in smbcloud-ascapi — branch + PR). -Decide: rewrite onto a feature branch, or leave. +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`.