Agent Guidelines

agent-guidelines is ThatFactory's public, versioned source of truth for reusable instructions and development configuration. It centralizes stable decisions about Swift development, Redux architecture, testing, documentation, logging, packages, CI/CD, localization, and Xcode tooling while leaving product context and exceptions in each consuming repository.

The repository contains documentation and supporting configuration, not a Swift product. Consumers install a tagged release as a Git subtree at AgentGuidelines/, so every agent and supported tool sees ordinary version-controlled files at predictable paths.

How it fits together

                  thatfactory/agent-guidelines
                  versioned GitHub repository
                             |
                       tagged release
                         e.g. 0.0.3
                             |
                    git subtree add/pull
                             |
                             v
+---------------- Consumer project or package -----------------+
|                                                              |
|  AGENTS.md                                                   |
|  |-- local product/package context                           |
|  |-- concrete project paths                                  |
|  |-- local exceptions                                        |
|  `-- pointers to shared guidelines -----------------+        |
|                                                     |        |
|  AgentGuidelines/                                   |        |
|  |-- VERSION                                        |        |
|  |-- Configurations/                                |        |
|  `-- Guidelines/ <----------------------------------+        |
|      |-- Architecture/Redux.md                               |
|      |-- Swift/SwiftUI.md                                    |
|      |-- Testing/UnitTesting.md                              |
|      `-- Xcode/MCP.md                                        |
|                                                              |
|  Sources and project files                                   |
+----------------------------+---------------------------------+
                             |
              reads instructions and project files
                  +----------+----------+
                  v                     v
               Codex                Xcode agent
                  |
                  | Xcode MCP (`xcrun mcpbridge`)
                  v
                Xcode

The subtree does not automatically import every guide into an agent's context. A consumer's root or folder-scoped AGENTS.md tells the agent which shared guides to read for the task. The nearest local AGENTS.md can specialize or override the shared baseline.

Guideline catalog

• Redux architecture and physical folder organization
• Swift
• Swift style
• SwiftUI
• Swift format
• Localization
• Unit and integration testing
• Documentation
• Logging
• Swift packages
• Development and reusability
• CI/CD
• Git repositories and SSH-first cloning
• GitHub pull requests
• Xcode MCP and visual verification
• Xcode security audits

Only reference the guides that apply. A UI-agnostic package normally uses Swift, style, testing, documentation, logging, packages, CI/CD, and Xcode guidance, but not Redux or SwiftUI guidance.

Add to a consumer

From the consumer repository root, install a tagged release:

git subtree add \
  --prefix=AgentGuidelines \
  https://github.com/thatfactory/agent-guidelines.git \
    0.0.11 \
    --squash

Swift consumers that adopt the shared formatter expose its configuration at the repository root so Xcode and other tools discover it:

ln -s AgentGuidelines/Configurations/Swift/.swift-format .swift-format
ln -s AgentGuidelines/Configurations/Swift/.editorconfig .editorconfig

Keep the subtree tracked, but add this to the consumer's tracked .gitattributes so GitHub collapses synchronized guideline files in pull-request diffs by default:

# Synced from thatfactory/agent-guidelines; keep tracked but collapse GitHub diffs.
AgentGuidelines/** linguist-generated

Copy and adapt the consumer template. Keep the consumer file small: describe the product or package, map its concrete physical folders, point to the applicable shared guides, and state only genuine exceptions.

Update a consumer

Review the target release's changelog, then pull it deliberately:

git subtree pull \
  --prefix=AgentGuidelines \
  https://github.com/thatfactory/agent-guidelines.git \
    0.0.11 \
    --squash

Confirm AgentGuidelines/VERSION, ensure the .gitattributes rule above is present, review the subtree diff, validate local AGENTS.md pointers, and run the consumer's relevant tests. Keep the subtree update in its own commit, and identify the old and new versions plus the central release or pull request in the consumer pull-request description. Updates are intentionally not automatic: one guideline release cannot silently change every project.

Maintain the source of truth

1. Export current Xcode skills to a temporary review location when a new Xcode release materially changes agent behavior:

   xcrun agent skills export --output-dir <temporary-directory>

2. Compare relevant guidance with this repository and official Apple documentation.

3. Bring over durable policy, not the exported skill text or an SDK API catalog.

4. Remove obsolete or conflicting rules instead of accumulating historical alternatives.

5. Run python3 Scripts/validate_guidelines.py.

6. Update VERSION and CHANGELOG.md, open a pull request, and wait for approval before merging.

7. After the pull request has merged, create the matching tag and GitHub release.

Precedence

For a consumer task, apply instructions in this order:

1. The user's explicit request.
2. The nearest applicable consumer AGENTS.md.
3. The consumer root AGENTS.md.
4. The shared guides explicitly referenced by those files.

Official Apple documentation remains authoritative for API behavior. A local convention can deliberately narrow a choice, but it must not rely on behavior contradicted by the current SDK documentation.