GitHub's Spec Kit was in X's Today's News box on 8 November, with about 210 posts under a headline on bringing structure to vibe coding. The repository page showed roughly 145,500 stars that day, and the CLI's latest release on PyPI, 1.3.2, came out two days earlier.
Most of those posts explain what spec-driven development means. Far fewer deal with a project that already exists, has a signing setup somebody once fought with, and still has to get through App Review. This post covers that case: the commands that add Spec Kit to a Swift repo, what belongs in the constitution, how to write App Review requirements into a spec so the agent has to meet them, and a small script that refuses to call a feature done while its spec still has open questions.
A word on what was checked. Every Spec Kit command and path below comes from GitHub's docs or repository templates as they stood on 8 November 2026, and the Xcode commands come from Apple. Nobody ran this whole flow on a real Xcode project for this post. The gate script near the end ran on Linux against sample folders with a fake xcodebuild. Treat your first run as a test, on a branch.
What Spec Kit adds to a repo
Spec Kit is an MIT-licensed toolkit with a terminal CLI called specify and a set of commands that run inside your coding agent. The CLI does setup. The work happens in the agent's chat, one step at a time, and each step writes a Markdown file you can read and correct before the next step relies on it.
| Command | What it does | What it writes |
|---|---|---|
/speckit-constitution | Sets the project rules later steps are checked against. Run once per project. | .specify/memory/constitution.md |
/speckit-specify | Describes what to build and why, with no tech stack. | spec.md |
/speckit-clarify | Asks up to five questions about vague areas and records the answers in the spec. | spec.md |
/speckit-plan | Turns the spec into a design, using the stack and constraints you pass in. | plan.md and other design files |
/speckit-tasks | Produces a task list in dependency order. | tasks.md |
/speckit-analyze | Reads the spec, plan and tasks and reports conflicts and gaps. | Nothing. It never edits files. |
/speckit-implement | Works through the tasks in order. | Your code |
/speckit-converge | Compares the code with the spec, plan and tasks to find anything missed. | Appends to tasks.md only if it finds gaps |
Feature files live in a folder per feature. The tasks template points at specs/[###-feature-name]/, and an optional git extension handles the numbered branch names.
Spelling varies by agent. The reference pages write commands with a dot, as in /speckit.plan, while the real form depends on the agent and how it was installed. GitHub Copilot in its default skills mode uses /speckit-plan, and the Claude Code integration page shows the same hyphenated form. Codex skills use $speckit-plan. The integrations table has 43 entries, counting none and generic, and the keys most iOS developers will want are claude, codex, cursor-agent and copilot. The pages read for this post don't state Cursor's command spelling, so open its integration page before copying a command into it. The examples below use the hyphenated form.
Install it pinned, then work on a branch
You need Python 3.11 or newer, uv, and a supported agent already installed. Pin the version so a teammate who sets this up next month gets the same files:
uv tool install specify-cli==1.3.2
specify version
specify self check
Two details from the install guide are easy to miss. If specify-cli is already on your machine, the install command keeps the version you have, so compare specify version with PyPI. And specify version doesn't prove where the executable came from, which is why the guide tells you to stick to the official GitHub or PyPI channels.
Next, get to a clean tree on a new branch:
git status
git switch -c chore/add-spec-kit
The existing-projects guide asks for this because the --force flag can replace files at what it calls conflicting managed paths, and it doesn't list those paths. In an iOS repo that uses Claude Code, the files worth watching are the ones already in your agent folder. The Claude integration writes one skill per command to .claude/skills/speckit-<command>/SKILL.md and configures native events in .claude/settings.json. If your hooks or permissions already live in that settings file, read its diff before you commit anything. The integration page says --events false turns the events off.
specify init --here --force --non-interactive --integration claude
git status --short
git diff --name-only | grep -E '\.(swift|pbxproj|xcconfig|plist|entitlements)$'
That last line should print nothing. GitHub's guide says init adds the shared .specify/ files and the skill files for your agent, and that it doesn't rewrite your application or infer specs for code you already have. The grep confirms that on your repo. If a Swift file, the project file, an xcconfig, a plist or your entitlements file shows up as modified, stop and find out why before committing.
--here means the current directory, --force acknowledges that it isn't empty, and --non-interactive skips the arrow-key pickers. If your agent runs on another machine, add --ignore-agent-tools so the CLI stops looking for its executable locally.
If you already keep a lot of Claude skills, there's a context cost to think about. By default every skill Spec Kit installs can be invoked by the model, so each description sits in Claude's context and counts against the skill-listing budget. Passing --integration-options="--no-model-invocation" makes the core skills something only you can trigger. The docs warn against that option when an extension's mandatory hook runs a core command, because the model then can't call it. A later preset change can also put overridden core skills back to the default, and specify integration upgrade claude replaces stored options whenever you pass new ones, so restate anything you want to keep.
Be careful with the community catalog. The README tells you to review a community extension's source before installing it, and that advice carries weight when the thing you install runs with the same access your agent has to your repo.
Write the constitution from what is already true
The guide's advice here suits iOS projects well. Build the constitution from evidence such as the README, architecture notes, contribution guide and CI config, and don't invent standards to fill the template. A rule saying every view has a snapshot test, in a repo with no snapshot tests, will make every later planning step argue with reality.
Collect the facts first. Apple documents the -list form, and you swap -project for -workspace if you use CocoaPods or a workspace:
xcodebuild -list -project MyApp.xcodeproj
grep -m1 IPHONEOS_DEPLOYMENT_TARGET MyApp.xcodeproj/project.pbxproj
grep -rl "import StoreKit" --include='*.swift' . | head
Then give the agent facts and new rules in separate lists, so nobody later mistakes an aspiration for current practice:
/speckit-constitution Write principles only from what this repo already does.
Read the README, the CI config and the Xcode project before writing.
Facts about this project:
- Deployment target: [value from the project file]
- UI framework: [SwiftUI, UIKit or both, as the code shows]
- Test command: xcodebuild test -scheme [Scheme] -destination '[destination]'
- Secrets live in: [where they live today]
Rules we are adopting from today:
- Do not change the bundle ID, team, signing settings, entitlements
or capabilities unless the feature's spec says so.
- A task that adds data collection or a required reason API must also
update the privacy manifest in that task.
- If the app creates accounts, account deletion stays reachable in the app.
The signing rule pays for itself the first time an agent decides to "fix" a build error by changing the team or bundle identifier. Everything in that block in square brackets is yours to fill in from your own project. If you don't know one of the values, find it before you run the command, because the constitution is the file every later step reads.
Put App Review in the spec
/speckit-specify is where you state the outcome and the compatibility boundaries. GitHub's guide uses examples like preserved filters, authorization and existing API responses. For an iOS app, App Review's requirements belong in that same list. The agent can only be held to rules it was given, and a spec is a better place for them than a prompt you might forget to repeat.
Here is a spec request for a feature that AI-built apps often ship without, in-app account deletion:
/speckit-specify Add in-app account deletion from the Settings screen.
Why: the app creates accounts, and App Store Guideline 5.1.1(v)
requires account deletion to be offered inside the app.
Must keep working:
- Sign-in, sign-out and session restore on launch.
- Existing API responses for users who never delete.
Must be true for App Review:
- A reviewer using the demo account can reach deletion without
contacting support.
- The demo account still works when review tries it again later.
Out of scope: redesigning Settings, changing subscription screens.
That demo account line comes from Guideline 2.1(a), which asks for demo account details on apps with a login and for your back-end service to be switched on during review. Deleting the only demo account during a review is exactly the sort of case a generic prompt never mentions.
The same idea works for other features. Use this table as a starting list when you write the "Must be true" section.
| If the feature touches | Add this to the spec | From |
|---|---|---|
| Login | Demo account details ready for App Review, back end running during review | Guideline 2.1(a) |
| In-app purchases | A restore mechanism for any restorable purchase | Guideline 3.1.1 |
| Account creation | Account deletion offered inside the app | Guideline 5.1.1(v) |
| Any release | Tested on a real device before submission | Guideline 2.1(a) |
Keep Swift, frameworks and file names out of this step. The spec is the what and why, and the plan comes next.
Then run /speckit-clarify, optionally with a focus such as /speckit-clarify what the reviewer sees and every failure state. It asks at most five questions per run and you can repeat it before planning. The spec template marks unknowns with [NEEDS CLARIFICATION: ...], for example when an auth method or a retention period wasn't given. Answer those yourself. How long deleted account data stays on your server is a product and legal decision, and an agent's guess at it will read as confidently as a real answer.
Make the plan respect the Xcode project
/speckit-plan is where the stack goes in. The guide's instruction for existing repos is to confirm the design reuses your existing architecture, dependencies and test conventions. For iOS, add the things that go wrong in Xcode specifically:
/speckit-plan Use the existing [SwiftUI or UIKit] patterns and the
existing networking layer. No new package dependencies unless the plan
says why. Do not change signing, bundle ID or entitlements.
For every new Swift file, say which target compiles it and how it gets
into that target in this project.
Verify each phase with:
xcodebuild test -scheme [Scheme] -destination '[destination]'
The line about targets is there because a new Swift file on disk does nothing if the target doesn't compile it, and agents working from the terminal can leave files in that state. Your project's own setup decides what the fix looks like, so make the plan state it instead of letting each task improvise.
For the destination, Apple's Technical Note TN2339 documents the keys platform, name, id and OS, with name matching the simulator name shown in your run destination list. Use a simulator you actually have installed.
Read the tasks before anything runs
/speckit-tasks organizes work into Setup, Foundational, one phase per user story in priority order, and Polish. Task lines look like - [ ] T003 [P] Configure linting and formatting tools, where [P] means the task can run alongside others because it touches different files and has no dependencies.
That marker needs a human eye in an Xcode project. Two tasks that each add files can both end up editing project.pbxproj, which means they aren't independent even if their Swift files are. Remove [P] from any pair like that. While you're in the file, check for tasks that change signing or entitlements when the spec never asked for it, and tasks with no way of telling whether they worked.
Then run /speckit-analyze. It's read-only, so fix what it reports in the spec, plan or tasks and run it again until the report is clean enough to act on.
Implement in pieces, then converge
/speckit-implement accepts a scope argument for staged runs, so you can do the Setup phase, review it and continue. If checklists exist it counts unchecked items and asks before going ahead. GitHub's guide says to review code and artifact changes together, which matters more on a brownfield app because the spec's assumptions about your code can turn out wrong.
/speckit-converge runs after implement. It only ever appends to tasks.md, under a Convergence section, and never edits code. If it finds nothing, tasks.md stays unchanged and it reports that the implementation is Converged. If it adds tasks, you run implement and converge again.
The docs describe converge as an assessment of your code against the spec, plan and tasks. They don't describe it running your app on hardware, and Guideline 2.1(a) asks for on-device testing before you submit. So a Converged result tells you the code matches the documents and leaves the device question open.
A small gate before you trust "done"
This script stops at the cheap checks before spending time on a build. It looks for the three files, any unanswered NEEDS CLARIFICATION marker, and unchecked tasks, and only then runs your tests.
#!/usr/bin/env bash
# spec-gate.sh: refuse to call a Spec Kit feature done while it still has holes.
# Usage: ./spec-gate.sh specs/003-account-deletion MyApp 'platform=iOS Simulator,name=iPhone 16'
set -u
feature_dir="${1:?feature directory}"
scheme="${2:?scheme}"
destination="${3:?destination}"
status=0
for file in spec.md plan.md tasks.md; do
if [ ! -f "$feature_dir/$file" ]; then
echo "MISSING: $feature_dir/$file"
status=1
fi
done
if [ -f "$feature_dir/spec.md" ] && grep -n 'NEEDS CLARIFICATION' "$feature_dir/spec.md"; then
echo "OPEN: spec.md still has unanswered questions"
status=1
fi
if [ -f "$feature_dir/tasks.md" ]; then
open_tasks=$(grep -c '^[[:space:]]*- \[ \]' "$feature_dir/tasks.md" || true)
if [ "$open_tasks" -gt 0 ]; then
echo "OPEN: $open_tasks unchecked tasks in tasks.md"
status=1
fi
fi
if [ "$status" -ne 0 ]; then
echo "Gate failed before building."
exit "$status"
fi
xcodebuild test -scheme "$scheme" -destination "$destination"
If your project uses a workspace, add -workspace MyApp.xcworkspace to the last line. On Linux with a stand-in xcodebuild, the script passed a complete sample folder, stopped on a spec with an open marker and two unchecked tasks, stopped on a folder missing the plan and tasks files, and returned the test command's exit code when it failed. It hasn't been run against a real Xcode project.
Don't let an agent's own checkmarks be the only evidence. A ticked task is a claim, and the build and test run are what check it.
The pass only you can do on a device
Before you submit, install the build on a real iPhone and walk through the feature as a reviewer would. For the account deletion example that means:
- Delete the app, reinstall, and sign in from a fresh start using the demo account you'll give Apple.
- Reach the deletion screen using only what's visible in the app.
- Run deletion with a test account, then confirm the app returns to a signed-out state and doesn't crash on the next launch.
- Turn on airplane mode, try deletion again, and read the error message as a stranger would.
- Check that the demo account still signs in afterwards.
Write what you find back into the spec, and let the next run of the workflow pick it up from there.
When to skip the full workflow
Nine steps is a lot for a typo. For a text change or a one-line constant, edit the code and move on. The shorter documented path, specify, plan, tasks, implement and converge, suits a small feature with little ambiguity.
Bugs have their own route. Install the bundled extension with specify extension add bug and you get /speckit-bug-assess, /speckit-bug-fix and /speckit-bug-test, the last of which returns a verdict of verified, partial or failed. A crash report that names a line is a better fit there than in a new feature spec. An untested app idea has a separate extension, specify extension add assess, which ends in a decision of go, needs-clarification or kill.
The guide also warns against starting by documenting your entire existing system, unless that inventory is what you actually want. Pick one change that can be reviewed by itself. A spec describes the change you intend, and the code remains the record of how the app behaves today.
Decide what happens to the specs afterwards
The docs list four ways to keep them, and don't name a default:
- Flow-back keeps all three files editable, and accepted discoveries from implementation can update any of them.
- Flow-forward treats finished feature folders as a historical record, and changed requirements get a new folder.
- Living spec treats
spec.mdas the contract and regenerates the plan and tasks from it. - Constitution-only keeps just the constitution in version control and retires feature files after delivery. Spec Kit's own repository works this way, with
specs/ignored by git.
For a solo developer or a small iOS team, constitution-only or living spec looks like the lighter choice, since a folder of stale plans is one more thing an agent might read and believe. That's a judgment call for your team to make. If you retire feature files, move anything that must outlast them first: the reasoning behind a review-sensitive decision, for instance, or the note about why the demo account can't be deleted. Whichever you pick, the docs suggest recording it in the constitution so the next person knows the rule.
A short checklist for the first run
- Clean working tree, new branch, pinned
specify-cliversion. - Run init, then confirm no Swift, project, xcconfig, plist or entitlements file changed.
- Write a constitution with real facts and clearly labelled new rules.
- Write one small spec that includes its App Review requirements.
- Answer every
NEEDS CLARIFICATIONmarker yourself. - Remove
[P]from tasks that share the project file. - Implement by phase, converge, then run the gate script.
- Test on a real device before you submit.
If you use Claude Code with Xcode and want the project-context side already written, Claude Code + Xcode: The Production iOS Workflow Kit is a pay-what-you-want product on Gumroad starting at $18. Its page describes a copy-ready Claude Code system for SwiftUI and UIKit with 6 commands, 10 agents, 8 rules and a runnable Xcode sample. It's a separate product from Spec Kit and isn't made by GitHub.
Sources
- github/spec-kit repository and README
- specify-cli on PyPI (version 1.3.2, 6 November 2026)
- Adopting Spec Kit in an existing project
- Spec Kit installation guide
- Spec Kit quickstart
- Spec Kit command reference
- Spec Kit integrations table and integration CLI
- Claude Code integration notes
- Persisting specifications
- Spec template and tasks template
- Apple App Review Guidelines (2.1, 3.1.1, 5.1.1)
- Apple Technical Note TN2339: Building from the Command Line with Xcode

Comments