swift-package-agents-maintainer

Swift Package AGENTS Maintainer

Maintain one canonical AGENTS.md across Swift Package repositories. Prefer the bundled script for deterministic automation runs.

Workflow

Confirm scope and mode.
Use --repo <path> for a single repository.
Use --root <path> to scan recursively for repos containing Package.swift .
If neither --repo nor --root is provided, scan ~/Workspace by default.
Use --check for read-only drift detection in recurring automation.
Omit --check to apply updates.
Resolve the canonical file.
Default canonical file: assets/AGENTS.md in this skill.
If the user provides another canonical source, pass it with --canonical <path> .
Run synchronization.
Command: scripts/sync_agents_md.sh [--canonical <path>] (--repo <path> | --root <path>) [--check] [--verbose]
In apply mode, the script creates or updates AGENTS.md in each discovered Swift package repo.
In check mode, the script reports drift and exits non-zero if any repo differs.
Validate and report.
Summarize: scanned repos, unchanged repos, updated repos, and drift count.
For automation runs, include whether exit status indicates drift.

Defaults

Prefer --check for scheduled automation runs that only detect drift.
Prefer apply mode for user-invoked maintenance runs.
Treat a directory as a Swift package repo only when Package.swift is present.
Use ~/Workspace as the default discovery root on machines where Swift packages are stored there.
Use --root when your repositories live outside ~/Workspace .
Skip hidden/build dependency directories during scans (for example .git , any .* directory, .build , .swiftpm , node_modules ).
Skip Xcode-protected/generated directories during scans (for example *.xcworkspace , *.xcodeproj , DerivedData ).

Automation Prompting

Codex App automation fit: Strong. Use for recurring drift detection or scheduled apply runs.
Codex CLI automation fit: Strong. Use deterministic prompts that map directly to --check or apply mode.
Use references/automation-prompts.md for Codex App and Codex CLI templates with placeholders.
Keep mode, schedule, and workspace routing explicit to avoid accidental apply runs.

Troubleshooting

If the canonical file path is missing, stop and request or restore a valid canonical AGENTS.md .
If no repositories are discovered under --root , report that no Package.swift files were found.
If permissions block writes, rerun with an authorized workspace path or approved elevation.

Resources

scripts/

scripts/sync_agents_md.sh : Detect and apply canonical AGENTS.md changes across Swift package repos.

assets/

references/

references/automation-usage.md : Suggested recurring automation modes and output expectations.
references/automation-prompts.md : Codex App and Codex CLI automation templates with placeholders and guardrails.

Interactive Customization Flow

Load current effective customization settings first:
uv run python scripts/customization_config.py effective
Ask targeted customization questions:
Use references/customization-flow.md to drive knob-by-knob questions.
Confirm desired behavior changes and safety constraints.
Map requested changes to implementation files:
Update SKILL.md , references/* , and any runtime script files listed in references/customization-flow.md .
Persist durable customization state:
Start from customization.template.yaml defaults.
Apply approved overrides with uv run python scripts/customization_config.py apply --input <yaml-file> .
Durable path: ~/.config/gaelic-ghost/apple-dev-skills/<skill-name>/customization.yaml .
Optional override root: APPLE_DEV_SKILLS_CONFIG_HOME .
Report resulting effective configuration:
Re-run uv run python scripts/customization_config.py effective and summarize final active settings.
If the user asks to remove customization state, run uv run python scripts/customization_config.py reset .

Use references/customization-flow.md for skill-specific knobs, file mapping, guardrails, validation checks, and example requests.

Source Transparency