CodexBar Mobile — Agent Workflow

This file is the repo-level routing and quality gate for AI agents working on CodexBar Mobile (iOS). Detailed operational workflows live in skills.

Scope: We only work on the iOS app (CodexBarMobile/). Mac-side code is maintained upstream.

Current upstream alignment: see version.env at repo root — UPSTREAM_VERSION and UPSTREAM_SYNC_DATE are the authoritative fields. Do NOT consult plan.md for this — it's a human-curated planning doc and lags reality.

Required Skills

• Use $codexbar-git-workflow for branch creation, commit cadence, Git/GitHub push, PR, review loop, branch cleanup, and Todoist handoff.
• Use $release-codexbar for Mac signing/notarization/appcast/GitHub release work.
• Use $qa-test for live provider QA, menu proof, and release smoke tests.

Development Lifecycle

Every feature or fix follows this lifecycle. Review handoff is the default endpoint; release steps run only within the user's authorization.

┌───────────────────┬─────────────────────────────────────────────────┬─────────────────────┐
│       Step        │                   Description                   │       Output        │
├───────────────────┼─────────────────────────────────────────────────┼─────────────────────┤
│ 1. Research       │ Understand the problem, read code/SDK/data      │ Root cause or       │
│                   │ Check upstream repo + PRs for prior art         │ requirements doc    │
├───────────────────┼─────────────────────────────────────────────────┼─────────────────────┤
│ 2. Design         │ Write research doc in Research/, mark draft     │ Research/NNN-*.md   │
│                   │ Get user confirmation on approach               │                     │
├───────────────────┼─────────────────────────────────────────────────┼─────────────────────┤
│ 3. Implementation │ Write code in phases, protocol-first            │ Code changes        │
├───────────────────┼─────────────────────────────────────────────────┼─────────────────────┤
│ 4. Testing        │ Build, simulator, real device if needed         │ Tests pass          │
├───────────────────┼─────────────────────────────────────────────────┼─────────────────────┤
│ 5. Documentation  │ Update CHANGELOG, in-app release notes,         │ Traceable record    │
│                   │ research doc status → done                      │                     │
├───────────────────┼─────────────────────────────────────────────────┼─────────────────────┤
│ 6. Review handoff │ Local review → push/PR → PR review loop         │ Clean reviewed PR   │
├───────────────────┼─────────────────────────────────────────────────┼─────────────────────┤
│ 7. Release        │ Ask for merge/release approval; execute if given │ Authorized delivery │
└───────────────────┴─────────────────────────────────────────────────┴─────────────────────┘

Repository map

Use Git/GitHub for branch and commit operations. Create a task branch before implementation unless the request is read-only. Do not require Goal prompts to spell out branch names; choose the right branch shape from $codexbar-git-workflow.

Default development handoff

For implementation, fixes, refactoring, upstream sync, and workflow/documentation changes, follow Development Quality and Handoff: local validation and independent local Code Review → fix/retest until clean → push a task branch and create/update a PR → GitHub Codex Code Review until clean on the exact current head → stop and ask for merge and applicable Mac/iOS release decisions. This is the user's standing authorization for local review agents, task-branch pushes to origin, PR creation, and review requests/replies/resolution. It does not authorize merge, auto-merge, tags, draft/live release creation, appcast publication, TestFlight/App Review, or CloudKit schema deployment.

Read-only research, an expressly local-only task, and narrower user instructions override this default. Existing explicit merge/release authorization remains valid; do not ask again for an action already authorized. A local review does not replace the GitHub PR review gate. The same quality document defines affected-flow Duo regression, data integrity, evidence, and artifact-provenance requirements; Goal prompts should specify the task outcome rather than repeat these rules.

Definition of Done for release / upstream-sync work

Distinguish review-ready candidate delivery from authorized release completion. A development/upstream-sync task may stop at a clean reviewed PR while awaiting the user's merge/release decision; do not call that published or user-installable. When release/upload is in scope, done requires the requested artifacts and delivery, not just "code committed" or "pushed":

• Mac: signed + notarized Sparkle draft/release flow completed as requested
• iOS: archive/export/upload flow completed when upload/TestFlight is in scope
• appcast, versioning, CloudKit audit, release notes, and Todoist state are updated

Credentials live on the user's Mac. CodexBar-specific release secrets such as Sparkle live under ~/.codexbar-secrets/; Apple App Store Connect App Manager credentials are global Apple release/signing credentials under ~/.codex-secrets/apple/app-store-connect/; the Developer ID certificate is in Keychain. When the user has authorized release/upload work, run the release commands on this machine instead of only listing commands for the user. The complete release gate is docs/RELEASE-CHECKLIST.md; read it before every release or upstream-sync completion check.

Collaboration roles

Step 1 — Research

Before writing any code, understand the problem space.

• Read relevant source code, SDK docs, and real synced data
• Check upstream (steipete/CodexBar) for existing implementations or open PRs
• Save findings to CodexBarMobile/Research/NNN-feature-name.md

Step 2 — Design

• Write or update the research doc with chosen approach, data models, key files
• Set status appropriately (see research status flow below)
• Get user confirmation before implementation unless the request/Goal already confirms the approach. Ask about unresolved material product choices, not routine decisions covered by that authorization.

Research document status flow

draft → ready → in-progress → done
  │
  ├→ blocked-upstream   (waiting for upstream PR to merge)
  └→ dropped            (decided not to pursue)

Full status definitions and index are in CodexBarMobile/Research/README.md.

Step 3 — Implementation

• Follow protocol-first design: define interfaces before writing logic
• Phase large features into incremental, buildable steps
• Follow all coding rules below (localization, file conventions, etc.)

Step 4 — Testing

Apply Development Quality and Handoff to select the required validation and protect existing product behavior, including Duo. Documentation-only changes need document/contract checks and review, not an app rebuild, product release notes, or a version bump.

• Build with xcodebuild to verify compilation
• Run unit tests if applicable
• Verify on simulator or real device as needed
• Add or extend XCTest / Swift Testing coverage for provider, parser, model, and settings changes. Prefer backticked sentence names for Swift Testing cases and clear fictitious model names when test data is synthetic.
• Run focused swift test --filter ... checks for parser/provider fixes when possible, then the broader gate required by the release checklist.
• Never run tests/checks or ad-hoc validation that can display macOS Keychain prompts. Live provider probes, browser-cookie imports, codexbar usage against real accounts, and real SecItem reads must be explicitly requested; otherwise use parser tests, stubs, test stores, or KeychainNoUIQuery.
• App-group migration tests must inject dictionary-backed defaults, both snapshot URLs, a synthetic home, and a contained recording FileManager. UUID defaults suites and Keychain isolation flags do not isolate defaults search domains or filesystem access. Ordinary SettingsStore tests must not discover shared defaults or run app-group migration.
• macOS CI is brittle around headless AppKit status/menu tests. Prefer covering menu behavior through stable state/model seams (MenuDescriptor, ProvidersPane, CodexAccountsSectionState, etc.) instead of constructing live NSStatusBar/NSMenu flows unless the AppKit wiring itself is the thing under test.

Multi-device iCloud Sync Compatibility Gate

When a release changes Mac→CloudKit→iOS sync, Shared payloads, CloudKit schema, provider display data, cache behavior, or cross-version rendering, testing must follow docs/ios-sync-compatibility-testing.md. This is the canonical 2 Mac × 2 iPhone old/new compatibility gate. The release Research/NNN-*/03-testing.md records that release's actual pass/fail/substituted evidence; it is not the source of the reusable rule.

CI Policy — Fork Invariant

CI uses the durable two-layer policy in docs/ci-policy.md:

• Every PR update runs only PR Fast Checks (portable lint and policy guards).
• Expensive macOS/Linux matrices run once after merge, selected by the final diff, or by explicit manual full-CI dispatch.
• A verified upstream-sync/* merge reuses the published upstream release's successful heavy checks; fork-specific local/release gates still apply.
• During upstream merges, preserve .github/workflows/pr-fast.yml, the fork trigger model in .github/workflows/ci.yml, and Scripts/check_ci_policy.sh. Never resolve an upstream workflow conflict by restoring heavy CI on PR synchronize events.

Scripts/check_ci_policy.sh is part of portable lint and fails if another workflow adds a PR update trigger or the fast workflow gains heavy jobs. This policy is repository state, not agent memory.

Step 5 — Documentation

After user-facing iOS code is complete (documentation-only work is exempt):

1. Update CodexBarMobile/CHANGELOG.md — Keep a Changelog format (Added / Changed / Fixed)
2. Update in-app release notes in MobileReleaseNotesCatalog (in ContentView.swift) — plain language, 4-language localized
   • Same MARKETING_VERSION = same release notes block. As long as only the build number changes (e.g. 1.0.0 (15) → 1.0.0 (16)), all changes belong to the same release notes entry. Before adding a new line:
     1. Check if an existing line already covers this feature area.
     2. If yes → merge the new detail into that line (rewrite it to include the update).
     3. If no existing line covers it → add a new line.
   • Only create a separate ReleaseNotesVersion entry when MARKETING_VERSION itself changes (e.g. 1.0.0 → 1.1.0).
3. Update research doc status to done

Release notes — two audiences

Step 6 — Branch, Commit & GitHub Handoff

When work needs a branch, commit, push, PR, review loop, branch cleanup, or Todoist status update, load and follow $codexbar-git-workflow.

Follow the skill's local-before-push and PR review loops, including the exact-head review gate, explicit thread resolution, architecture audit after five rounds, and bounded stalled-review recovery. PR Fast Checks alone is insufficient. Run Scripts/check_pr_review_gate.sh <pr> at approval handoff and again immediately before an authorized merge. Gate success does not authorize merging, auto-merge, tags, or public release/appcast work. TestFlight is an independent beta workflow: an authorized upload does not require a PR, a clean CR gate, a merge, or remote CI completion. Keep local build/test, versioning, four-language notes, signing, and CloudKit Production checks; record the source commit and any known beta validation gaps. Before App Review/public release, verify that the selected ASC build was archived from the clean reviewed release code/resources/build configuration/version, using recorded source and artifact provenance. If review fixes changed shipped inputs or provenance is missing, archive/upload a new build; a later clean PR does not validate an older unreviewed binary.

For large Goals, make coherent staged commits within the authorized scope. Default task-branch push/PR authorization and the separate merge/release boundary are defined above; explicit user restrictions take precedence.

Version number format

iOS (project.yml) — these are CFBundle fields:

• MARKETING_VERSION = user-facing version, e.g. 1.7.0 (feature releases only)
• CURRENT_PROJECT_VERSION = build number, e.g. 129
• Displayed as: 1.7.0 (129)

Mac (version.env) — fork-specific scheme with subdecimal patches. Full rules + decision tree + sparkle:version explanation: → docs/versioning.md (read this first when bumping Mac MARKETING_VERSION / BUILD_NUMBER / MOBILE_VERSION / UPSTREAM_VERSION).

Step 7 — Push & Release

CloudKit Environment — CRITICAL

All builds (Mac and iOS) must use CloudKit Production environment:

• Mac (Scripts/package_app.sh): entitlements must include com.apple.developer.icloud-container-environment = Production
• iOS (CodexBarMobile/CodexBarMobile.entitlements): must include com.apple.developer.icloud-container-environment = Production
• iOS via Xcode debug: also uses Production (set in entitlements), so Xcode installs and TestFlight share the same CloudKit database

If this entitlement is missing, Mac defaults to Development environment and TestFlight iOS uses Production — data goes to different databases and sync appears broken.

CloudKit Schema Deploy — pre-release audit

Before every Mac release: run the audit in docs/cloudkit-deploy-audit.md to decide whether the Production schema needs a Dashboard deploy. Catches the recurring "I added a field but forgot to deploy" trap. Verdict table + grep commands + historical record live in that doc.

iOS — Archive & Upload

When the user asks to upload / archive / release:

# 1. Generate Xcode project
cd CodexBarMobile && xcodegen generate

# 2. Archive
xcodebuild -project CodexBarMobile.xcodeproj -scheme CodexBarMobile \
  -destination 'generic/platform=iOS' -configuration Release \
  -archivePath /tmp/CodexBarMobile.xcarchive archive -allowProvisioningUpdates

# 3. Export & upload to App Store Connect
xcodebuild -exportArchive \
  -archivePath /tmp/CodexBarMobile.xcarchive \
  -exportOptionsPlist /tmp/ExportOptions.plist \
  -allowProvisioningUpdates

Mac — Sign, Notarize & Release

Complete workflow: docs/RELEASING-MOBILE.md

Quick summary:

1. Update CHANGELOG.md — Mobile changes first, upstream second
2. ./Scripts/sign-and-notarize.sh — builds, signs with Developer ID Application: Yuxiao Wang (3TUERHN53E), notarizes
3. Generate appcast with make_appcast.sh (set SPARKLE_DOWNLOAD_URL_PREFIX to full tag URL)
4. Create GitHub release on o1xhack/CodexBar-Mobile (not upstream)
5. Push appcast to mobile-dev

Build number: BUILD_NUMBER.MOBILE_VERSION (e.g. 53.1.1.0). See docs/sparkle.md for details.

Coding Rules

Version Control — Git/GitHub

Use Git/GitHub for branch, commit, push, PR, review, and branch cleanup work. Do not use jj unless the user explicitly re-enables it. Operational details belong in $codexbar-git-workflow, not in individual Goal prompts.

Operational guardrails

• Do not modify Mac-only files such as Sources/ or Tests/ unless the user explicitly asks for Mac/upstream-sync/release work.
• Never push to upstream; only push to origin.
• README.md is the fork-owned iOS/Mac download entrypoint. During every upstream merge or conflict resolution, keep it byte-for-byte from the fork (mobile-dev) side; never accept or incidentally port the upstream README. After the merge, separately audit the upstream README diff for factual product, security, or troubleshooting changes and deliberately adapt only applicable text without replacing fork identity/download content. Scripts/check_fork_readme.sh enforces the resulting reviewed fork content hash. Do not update that hash merely to make an upstream sync pass; update it only with an intentional, separately reviewed fork README change.
• Do not hand-edit .xcodeproj; update project.yml and run xcodegen generate.
• Do not skip build numbers, changelog, release notes, CloudKit audit, or localization checks when their step applies.
• Do not add full build/test matrices to PR update events. Follow docs/ci-policy.md; full CI belongs after merge or explicit manual dispatch.

Localization — Mandatory 4-Language Rule

Every user-facing text change MUST include all 4 languages. No exceptions.

Languages: English (en), Simplified Chinese (zh-Hans), Traditional Chinese (zh-Hant), Japanese (ja).

• Source language is English
• All strings use String(localized:) — the key is the English text itself
• Translations live in Localizable.xcstrings (JSON format)
• Every entry must have all 4 translations with "state": "translated"

Needs translation: UI labels, buttons, titles, descriptions, footers, placeholders, error messages, in-app release notes, onboarding text, empty states.

Does NOT need translation: Code comments, log messages, debug strings, accessibility identifiers, keys, enum raw values, format specifiers.

Self-check before finishing

• Every new String(localized:) has a matching entry in Localizable.xcstrings
• Every entry has all 4 languages with "state": "translated"
• No "state": "new" or missing language keys left behind

Quick Reference

Trigger phrases

Key paths