Guides

Agent Fast Start

Where agents should look first when working inside the ShipItSwifty repo.

On this page

This page is a compact navigation guide for coding agents working in the ShipItSwifty repository.

Purpose

ShipItSwifty is a Swift 6 release-automation toolkit for iOS and Android.
ShipItKit contains the domain logic and machine-facing contracts.
shipit is the CLI layer over that library.

Authoritative sources

Concern	Source of truth
Runtime config resolution	`Sources/ShipItKit/Config/ConfigResolver.swift`, `Sources/ShipItKit/Config/ResolvedConfig.swift`
Shipfile model	`Sources/ShipItKit/Config/Shipfile.swift`
Environment variable mapping	`Sources/ShipItKit/Config/Environment.swift`
Built-in action option schema	`Sources/ShipItKit/Introspection/BuiltInSchemaCatalog.swift`
AI-session JSON contract	`Sources/ShipItKit/Introspection/AISessionTypes.swift`, `Sources/ShipItKit/Introspection/AISessionBuilder.swift`
Action behavior	`Sources/ShipItKit/Actions/<ActionName>.swift`
CLI command surface	`Sources/CLI/Commands/`
Executable behavior spec	`Tests/ShipItKitTests/`, `Tests/CLITests/`

Start here by task

Task	Start here
Config resolution bug or feature	`Sources/ShipItKit/Config/ConfigResolver.swift`, `ResolvedConfig.swift`, `Environment.swift`, `Shipfile.swift`
Action implementation or regression	`Sources/ShipItKit/Actions/`, matching tests in `Tests/ShipItKitTests/`
Workflow or custom action behavior	`Sources/ShipItKit/Actions/WorkflowTypes.swift`, `CompositeAction.swift`, workflow-related tests
Schema or validation drift	`BuiltInSchemaCatalog.swift`, `SchemaValidator`, `ShipfileValidator`, related tests
AI-session output drift	`AISessionTypes.swift`, `AISessionBuilder.swift`, `AISessionTests.swift`
CLI parsing or output behavior	`Sources/CLI/Commands/`, `Tests/CLITests/`
Coverage/reporting behavior	`Sources/ShipItKit/Actions/Coverage.swift`, parser helpers, `CoverageActionTests.swift`
Docs sync work	`AGENTS.md`, `docs/features.md`, `docs/configuration-reference.md`, `docs/architecture.md`

Change impact map

If you change...	Also check/update...
An action `Options` or `Result` type	`BuiltInSchemaCatalog.swift`, tests, `docs/features.md`, `AGENTS.md` if command guidance changed, `AISessionBuilder.swift` if agent-facing guidance changed
Shipfile schema	`Shipfile.swift`, `BuiltInSchemaCatalog.swift`, `docs/configuration-reference.md`, validation tests
`ai session` payload shape or semantics	`AISessionTypes.swift`, `AISessionBuilder.swift`, `docs/architecture.md`, `AGENTS.md`, `AISessionTests.swift`
CLI command flags or subcommands	`Sources/CLI/Commands/`, `AGENTS.md`, `docs/features.md`, CLI tests
Runtime config behavior	`ConfigResolver.swift`, `ResolvedConfig.swift`, `Environment.swift`, config tests
Workflow/composite execution	`WorkflowTypes.swift`, `CompositeAction.swift`, workflow/composite tests

Recommended first-read paths

Package.swift
AGENTS.md
Sources/ShipItKit/Config/ConfigResolver.swift
Sources/ShipItKit/Config/ResolvedConfig.swift
Sources/ShipItKit/Actions/
Sources/ShipItKit/Introspection/
Tests/ShipItKitTests/

Agents driving a project through shipit should read structured results instead of scraping console output. shipit ai session, shipit ai instructions, and shipit ai skills all carry this guidance:

Read build/test-runs/<run>/report.json (or the file written by --report-path) and its per-attempt evidence. For saved artifacts, run shipit test-results --input <path> --output json.
Results state the runner, buildSystem, and destinations separately, count attempts per test, and mark tests that passed only after a retry as flaky. A green run can still contain flaky tests, so report them.
A run with zero results is a failure. Never mark a run green from the exit code alone when the report says otherwise, and never edit a report or its evidence to change an outcome.
Two built-in playbooks cover this: shipit ai skills show test-workflows (package, Xcode, Gradle, Flutter, and Jest workflows with reruns, evidence, and CI export) and shipit ai skills show investigate-test-failures (triage from the typed report).

See Test Results & Workflows for the report format.

Validation commands

swift build
swift test --filter ShipItKitTests
swift test --filter CLITests
swift test --enable-code-coverage

Use more targeted filters when the change is localized, for example:

swift test --filter AISessionTests
swift test --filter IntrospectionTests
swift test --filter GenerateProjectActionTests
swift test --filter WorkflowAutoGenerationTests

Security & Credentials

Firebase App Distribution

Edit this page on ShipItSwifty