docs(agents): add git branching workflow and ASC session plan (#30)
* 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 <noreply@sigit.si> * 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 <noreply@sigit.si> --------- Co-authored-by: siGit Code v1.6.7-acp <noreply@sigit.si>
Seto Elkahfi committed
Oct 12, 2026 at 00:23 UTC
679a121e6fe0983fd76a0236a5bd5ff599f526f8
2 files changed
+76
.agents/AGENTS.md
+18
@@ -68,6 +68,24 @@ stale `AuthKey_<id>.p8` and fail with a 401, and `--auth-string` would put
68
the key in the process table. Upload is CLI-only, because a tool call that
69
blocks for minutes and publishes a build doesn't belong in MCP.
70
71
+## Git branching workflow
72
+
73
+Branches flow in one direction: `main` ← `development` ← feature branch.
74
+
75
+- `main` is the release branch. Never commit to it directly; it only advances
76
+ by merging `development`.
77
+- `development` is the integration/base branch. Never commit to it directly
78
+ either — every change lands through a pull request.
79
+- Do the work on a short-lived **feature branch** cut from `development`
80
+ (`feat/…`, `fix/…`, `docs/…`), then **open a PR into `development`**. Let CI
81
+ (fmt / clippy `-D warnings` / test / doc / lower-crate solo builds) pass
82
+ before merge.
83
+- When `development` is ready to release, it is merged into `main` via its own
84
+ PR — not by pushing commits onto `main`.
85
+
86
+So: branch off `development`, push the feature branch, open a PR → `development`.
87
+Do not commit straight to `development` or `main`.
88
+
89
## Verify before committing
90
91
CI (`.github/workflows/ci.yml`, ubuntu + macOS) runs these, and warnings are
.agents/plans/from-splitfire-ai-apps-session.md
new
+58
@@ -0,0 +1,58 @@
1
+# Findings — SplitFire AI apps release session (KaroKowe Jam TestFlight)
2
+
3
+Context: shipping a macOS build (KaroKowe Jam) to TestFlight via the `asc`
4
+CLI. Concrete app id / bundle id / build number are omitted — this is a public
5
+repo; keep plan files to generalizable `asc` findings, not per-app identifiers.
6
+
7
+## 1. The release `asc` binary can silently lag `development`
8
+
9
+The installed/release `asc` predated the `testflight` subcommand, yet
10
+`asc apps upload` still worked — because upload only shells out to `altool`
11
+and doesn't touch the newer code paths. So an upload succeeding is **not**
12
+evidence that the binary is current.
13
+
14
+**Rule:** before relying on a newly-added subcommand (e.g. `testflight`),
15
+rebuild `asc` from `development` first (`cargo build --release`), or you'll hit
16
+`unrecognized subcommand` on a binary that otherwise looks healthy.
17
+
18
+## 2. `testflight groups` takes a nested subcommand, not an app id
19
+
20
+`asc testflight groups <APP_ID>` fails with
21
+`error: unrecognized subcommand '<APP_ID>'`. The app id is an argument of the
22
+leaf command, not of `groups`. Confirmed command surface:
23
+
24
+```
25
+asc testflight groups list <APP_ID>
26
+asc testflight groups get <GROUP_ID>
27
+asc testflight groups add-build --build-id <BUILD_ID>... <GROUP_ID>
28
+
29
+asc testflight app-review-detail get <APP_ID>
30
+asc testflight app-review-detail update ... # contact + demo-account details
31
+
32
+asc testflight app-review-submissions list <BUILD_ID>
33
+asc testflight app-review-submissions submit <BUILD_ID>
34
+```
35
+
36
+Notes:
37
+- `groups add-build` and `app-review-submissions submit` are **CLI-only** by
38
+ design (adding a build to an external group / submitting to Beta App Review
39
+ can trigger review — not something an MCP tool call should do unattended).
40
+- Both support `--dry-run` to print the request body before writing.
41
+
42
+## 3. Finish-the-release recipe (for next time)
43
+
44
+1. Upload: `asc apps upload <PKG> --wait` (always `--p8-file-path`; never the
45
+ script's raw `altool`, which can pick a stale `AuthKey_<id>.p8` → 401).
46
+2. Poll to VALID: `asc apps builds <APP_ID> --version <BUILD_NUMBER>` → grab the
47
+ build id once `processingState` is VALID.
48
+3. Beta review contact details: `asc testflight app-review-detail update ...`.
49
+4. Submit: find the Public Link group via `asc testflight groups list <APP_ID>`,
50
+ then either `groups add-build --build-id <BUILD_ID> <GROUP_ID>` or
51
+ `app-review-submissions submit <BUILD_ID>`.
52
+
53
+## 4. Process note
54
+
55
+Plan files and any other changes land on a feature branch and go in through a
56
+PR — never a direct commit to `development` (or `main`). It's easy to slip when
57
+a change feels like "just docs"; treat the branching rule as unconditional.
58
+See the **Git branching workflow** section of `AGENTS.md`.