Project Kickoff
3 min read
Project Kickoff
Three things happen in this doc: you create the Xcode project, you scaffold the project structure Claude Code needs, and you set up version control. Do them in order. Every subsequent doc assumes this foundation is in place.
Step 1: Name your app and create the Xcode project
Choose your name carefully — the Bundle ID ties to your Apple Developer account and is painful to change after App Store submission.
- App name: what users see on their home screen. Short, memorable, no spaces in the internal name.
- Bundle ID: reverse-domain format: com.yourname.appname. All lowercase, no spaces. Example: com.jiffi.buildtracker
- Open Xcode and choose Create New Project
- Select iOS → App
- Fill in: Product Name, Bundle Identifier, Team (your Apple ID), Interface: SwiftUI, Language: Swift
- Uncheck Include Tests for now (you'll add them in Test and Verify)
- Save to ~/workspace/{YourAppName}/
Step 2: Set up Git immediately
cd ~/workspace/YourAppName
git initgit checkout -b main
# Proper iOS .gitignorecurl -o .gitignore https://raw.githubusercontent.com/github/gitignore/main/Swift.gitignore
# Append common extrascat >> .gitignore << 'EOF'
# macOS.DS_Store*.DS_Store
# Xcode user state (never commit)*.xcuserstatexcuserdata/*.xcscmblueprint
# Derived data and archivesDerivedData/*.ipa*.xcarchive
# SPM build artefacts.build/.swiftpm/
# Claude Code local state.claude/settings.local.jsonEOF
git add .gitignoregit commit -m "chore: initialise iOS project with .gitignore"# Push to GitHub (creates private repo)gh repo create YourAppName --private --source=. --pushStep 3: Run the Project Scaffold — Part A
Open a Claude Code session in your project directory, paste this prompt exactly. Claude creates all files and folders.
cd ~/workspace/YourAppNameclaudePaste this into the Claude Code session:
iOS Project Scaffold (Team Standard) — Part A: Structure, Rules, and Coordination
You are setting up a new iOS project. Create the following structure and files exactly as specified.Do not ask questions — just create everything listed below.
################################################################################1. Create the folder structure inside the Xcode project folder:
docs/docs/idea/docs/prd/docs/adr/docs/adr/template.mddocs/agents/docs/design-system/.claude/.claude/rules/.claude/commands/.claude/agents/.claude/hooks/
Note: The Xcode source files stay in the YourAppName/ subfolder Xcode created.Do NOT move or reorganise the Xcode project structure.
################################################################################2. Create CLAUDE.md at the project root (next to the .xcodeproj file):
# Project: [PROJECT_NAME]
## Overview[To be filled during Idea Pack phase]
## Platform- iOS 18+ minimum deployment target- Swift 6, SwiftUI, Xcode 16+- iPhone only (iPad deferred — update if scope changes)
## Architecture[To be filled during Architecture phase]
## Commands- Build: xcodebuild -scheme [PROJECT_NAME] -destination 'platform=iOS Simulator,name=iPhone 16'- Test: xcodebuild test -scheme [PROJECT_NAME] -destination 'platform=iOS Simulator,name=iPhone 16'
## Current PhaseScaffold — not yet started
## Key Documents- Idea Pack: docs/idea/idea-pack.md- PRD: docs/prd/prd.md- Acceptance checklist: docs/prd/acceptance-checklist.md- ADRs: docs/adr/- Design system: docs/design-system/DESIGN-SYSTEM.md- Agent coordination: AGENTS.md
## Rules- Never commit secrets, API keys, or credentials- Run the test suite after every code change- One phase at a time — never build the whole app at once- Stay below 60% context utilisation — /clear between phases- Never work directly on main — always use feature branches- Every SwiftUI view file must have a #Preview {} at the bottom- Never use force unwrap (!) — use guard let or if let- Never use ObservableObject, @Published, or NavigationView in new code
## Testing- Framework: Swift Testing (@Test, @Suite) for unit tests, XCUITest for UI tests- Run: xcodebuild test -scheme [PROJECT_NAME] -destination 'platform=iOS Simulator,name=iPhone 16'- Coverage target: 80%+ on Core/ and Features/ ViewModels
################################################################################3. Create AGENTS.md at the project root:
# AGENTS.md — Contract-First Team Coordination
This file is the single source of truth for how agents work on this project.Every teammate reads this independently — it must be explicit, no assumptions.
## Architecture Rules[To be filled during Architecture phase. Examples:]- All @Observable view models must be @MainActor- All network calls in Core/APIClient/ — never directly in views or view models- SwiftData models in Core/Storage/- One type per file — file name matches type name exactly- Every View file has a #Preview {} macro at the bottom
## File Ownership (Critical for Teams)| Directory | Owner | Notes ||-----------|-------|-------|| [AppName]/Features/ | Feature teammate | Views + ViewModels per feature || [AppName]/Core/APIClient/ | API teammate | Network layer || [AppName]/Core/Storage/ | Data teammate | SwiftData models and queries || [AppName]/Components/ | UI teammate | Reusable SwiftUI views || [AppName]Tests/ | Test teammate | Unit tests || [AppName]UITests/ | Test teammate | UI tests || docs/ | Lead | Documentation only |
[Update this table after Architecture phase to match real folder names]
## Code Standards- Swift 6 strict concurrency — all view models @MainActor- @Observable for all view models (never ObservableObject)- NavigationStack for all navigation (never NavigationView)- async/await for all async work- No force unwrapping — guard let or if let everywhere- No hardcoded colours, fonts, or sizes — use DS.Color.*, DS.Spacing.*, DS.Radius.*
## Team PatternsPattern 1 — Feature Squad: UI agent + Data agent + Test agentPattern 2 — Research Debate: two agents argue approaches, lead decidesPattern 3 — Parallel Processor: N agents, each owns distinct files
## Lead Mode- Plan mode (default): 2-3 teammates, lead participates in execution- Delegate mode (Shift+Tab): 4+ teammates, lead coordinates only
################################################################################4. Create .claude/rules/security.md:--- description: Security rules for all code ---- Never commit credential files- Never hardcode API keys, passwords, or tokens- Always use environment variables or iOS Keychain for sensitive values- Never store sensitive data in UserDefaults — use Keychain- Deny access to: .env, .env.*, secrets.*, credentials.*
################################################################################5. Create .claude/rules/testing.md:--- description: Testing rules for all code ---- Run xcodebuild test after every code change- Use Swift Testing (@Test, @Suite) for unit tests- Use XCUITest for UI flows- 80% coverage target on Core/ and Features/ ViewModels- Test happy path, error state, empty state, offline state- Never mark a phase complete until all tests pass on iPhone SE and iPhone 16 Simulators
################################################################################6. Create .claude/rules/context-management.md:--- description: Context window management rules ---- Never exceed 60% context utilisation before clearing- Use /clear between build phases- Use /compact with a focus instruction when context grows large- Break large tasks into phases — never build the whole app in one go
################################################################################7. Create .claude/rules/git.md:--- description: Git workflow rules ---- Never commit directly to main- Always work on a feature branch: feature/[description] or fix/[description]- Commit after each successful build phase- Project must build without errors before committing- Run the test suite before committing
################################################################################8. Create .claude/rules/ios-conventions.md:--- description: iOS and Swift conventions for this project ---- Architecture: MVVM with @Observable — never ObservableObject or @Published in new code- All @Observable view models must be @MainActor- Navigation: NavigationStack only — never NavigationView- One type per file — file name matches type name exactly- Every SwiftUI view: #Preview {} at the bottom- No force unwrapping anywhere- No hardcoded colours — DS.Color.* from Assets.xcassets- No hardcoded font sizes — .font(.body), .font(.headline) etc.- Liquid Glass: always gated behind #available(iOS 26, *) with .ultraThinMaterial fallback- Minimum touch target: 44x44pt
################################################################################9. Create .claude/rules/agent-teams.md:--- description: Rules for agent team coordination ---Use teams when: phase touches 3+ layers AND modifies 8+ files AND teammates need shared interfaces.Otherwise: solo or sub-agents.Read AGENTS.md before any team work.Respect file ownership — never edit files outside assigned scope.All teammates run tests before reporting complete.Lead cleans up teammate sessions when work is complete.
################################################################################10. Create docs/adr/template.md:
# ADR-[NUMBER]: [Title]**Status:** Proposed | Accepted | Deprecated | Superseded**Date:** YYYY-MM-DD**Decision makers:** [names]
## ContextWhat is the issue or question?
## DecisionWhat was decided?
## ConsequencesPositive, negative, and neutral consequences.
## Alternatives consideredWhat else was evaluated and why was it rejected?
################################################################################
After creating everything, show the full directory tree so I can verify before Part B.WHEN COMPLETE: run /clear, then start Part B.Verify Part A output
- CLAUDE.md at project root (next to .xcodeproj)
- AGENTS.md at project root
- docs/ with idea/, prd/, adr/, design-system/ subdirectories
- .claude/rules/ with 5 files: security.md, testing.md, context-management.md, git.md, ios-conventions.md, agent-teams.md
- docs/adr/template.md
Step 4: Run the Project Scaffold — Part B
Part B creates the three build commands that drive the entire build phase — these are the most important outputs of the scaffold. Once they exist, you never manually decide what to build next:
- /build-next — reads the acceptance checklist, finds the first unchecked user story, builds it completely (view, viewmodel, data, error states, empty states, unit tests), marks the ACs done, commits. Run this once per user story, repeatedly until all ACs are checked.
- /build-status — shows a progress table: every user story, ACs done vs total, what is next. Run anytime.
- /build-polish — applies Liquid Glass, spring animations, haptics, and accessibility labels. Refuses to run if any ACs are still unchecked.
These three commands plus run-tests, security-audit, and create-adr are all inside the Part B prompt below (items 12–17). Paste the prompt and Claude Code creates all six files in .claude/commands/ automatically.
After running /clear, paste Part B. This creates the build commands — the most important outputs of the entire scaffold. These commands are what you run throughout the build phase instead of manually figuring out what to do next.
iOS Project Scaffold (Team Standard) — Part B: Config, Build Commands, and Hooks
Parts A has already been completed. Read CLAUDE.md and verify the folder structure exists.Do not ask questions — just create everything listed below.
################################################################################11. Create .claude/settings.json:
{ "permissions": { "deny": [ "Read(.env*)", "Read(secrets.*)", "Read(credentials.*)", "Write(.env*)" ] }}
################################################################################12. Create .claude/commands/build-next.md:
---description: Build the next user story from the acceptance checklist — one US at a time, all ACsallowed-tools: Read, Write, Bash---
You are the build controller. Build exactly ONE user story, completely, then stop.
## Step 1: Read project contextRead ALL of these before doing anything:- CLAUDE.md- docs/prd/prd.md- docs/prd/acceptance-checklist.md- docs/design-system/DESIGN-SYSTEM.md- docs/adr/README.md
## Step 2: Find next user storyFind the FIRST user story in docs/prd/acceptance-checklist.md with any unchecked items (- [ ]).If ALL items are checked: print "All complete — run /build-polish" and stop.
## Step 3: Build the complete user storyRead all ACs for this US from docs/prd/prd.md.
For each AC implement exactly what is described:- Happy path: the behaviour specified- Error state: DS.Color.error + user-facing message (not internal errors)- Edge case: handle the specific edge case- Empty state: SF Symbol + descriptive text, never a blank screen
Create:- Features/[Name]/[Name]View.swift — SwiftUI, @Query where needed, #Preview {} at bottom- Features/[Name]/[Name]ViewModel.swift — @Observable, @MainActor, all state and actions- New @Model classes in Core/Storage/ if PRD data model requires new entities- Wire into existing navigation per CLAUDE.md navigation structure
Design system (enforce — never hardcode):- DS.Color.* for all colours- DS.Spacing.* for all padding and margins- DS.Radius.* for all corner radii- DS.Animation.* for all transitions
## Step 4: TestsWrite @Test functions in [AppName]Tests/ for ViewModel state transitions and business logic.
## Step 5: Build and testxcodebuild build -scheme [SCHEME FROM CLAUDE.md] -destination 'platform=iOS Simulator,name=iPhone 16'Fix all errors.xcodebuild test -scheme [SCHEME FROM CLAUDE.md] -destination 'platform=iOS Simulator,name=iPhone 16'Fix all test failures.Both must pass before continuing.
## Step 6: Update checklistIn docs/prd/acceptance-checklist.md:- [ ] AC-00X.Y → - [x] AC-00X.Y for every implemented ACIf an AC is blocked (backend/device only): leave unchecked, add <!-- blocked: reason -->
## Step 7: Commitgit add -A && git commit -m "feat: [US-00X] [user story name]"
## Step 8: Report- User story built: US-00X- ACs checked: N of M- Blocked ACs: [list if any]- Test manually on Simulator: [what automated tests cannot cover — haptics, camera, animations, VoiceOver]- Next: run /build-next → will build [next US from checklist]
################################################################################13. Create .claude/commands/build-status.md:
---description: Show build progress — user stories, AC counts, what is nextallowed-tools: Read---
Read docs/prd/acceptance-checklist.md and docs/prd/prd.md.
Print a table of every user story:| User Story | Description | ACs Total | ACs Done | Status |Status values: Complete / In progress / Queued
Print summary:- Total ACs, complete count and percentage, remaining count- Any blocked ACs with reasons (<!-- blocked: ... --> comments in checklist)- What to run next: /build-next (ACs remain) or /build-polish (all done)
################################################################################14. Create .claude/commands/build-polish.md:
---description: Polish pass — Liquid Glass, animations, haptics, accessibility — run after all ACs checkedallowed-tools: Read, Write, Bash---
Read docs/prd/acceptance-checklist.md.Count unchecked items (- [ ]).If ANY exist: print "N ACs unchecked. Run /build-next first." and stop.
Read CLAUDE.md and docs/design-system/DESIGN-SYSTEM.md.
Apply in order:
1. Liquid Glass (surfaces from DESIGN-SYSTEM.md only) Every use: if #available(iOS 26, *) { .glassEffect() } else { .background(.ultraThinMaterial) }
2. Spring animations (DS.Animation.*) - List/grid items: .animation(DS.Animation.standard, value: trigger) - Button press: .scaleEffect(pressed ? 0.96 : 1.0).animation(DS.Animation.snappy, value: pressed) - Modals/sheets: .animation(DS.Animation.expressive) on content inside
3. Haptics - Primary action: UIImpactFeedbackGenerator(.medium).impactOccurred() - Success: UINotificationFeedbackGenerator().notificationOccurred(.success) - Error: UINotificationFeedbackGenerator().notificationOccurred(.error) - Destructive: UINotificationFeedbackGenerator().notificationOccurred(.warning)
4. Accessibility - Every Button: .accessibilityLabel("Verb + what") - Every meaningful image: .accessibilityLabel("description") - Every decorative image: .accessibilityHidden(true) - Every TextField: .accessibilityLabel + .accessibilityHint if purpose is not obvious
5. Dark mode audit — switch Simulator to dark mode All colours should adapt via DS.Color.* — report any hardcoded values.
6. Dynamic Type audit — set Simulator to largest accessibility text All text uses .font(.body) etc — fix any .frame(height:) that clips text.
xcodebuild build → fix all errorsxcodebuild test → fix all failuresgit add -A && git commit -m "feat: polish pass — glass, animations, haptics, accessibility"
Report what was applied and any issues fixed. State: ready for Test and Verify doc.
################################################################################15. Create .claude/commands/create-adr.md:
---description: Create a new Architecture Decision Recordallowed-tools: Write, Read---Create a new ADR in docs/adr/ using the template at docs/adr/template.md.Number sequentially from existing ADRs.Ask for: title, context, and decision to record.Save as docs/adr/ADR-[NNN]-[kebab-title].md with status Accepted.
################################################################################16. Create .claude/commands/run-tests.md:
---description: Run the full test suite on both Simulator targetsallowed-tools: Bash, Read---xcodebuild test \ -scheme [PROJECT_NAME from CLAUDE.md] \ -destination 'platform=iOS Simulator,name=iPhone SE (3rd generation)' \ -destination 'platform=iOS Simulator,name=iPhone 16 Pro Max'
Report: total tests, passed, failed, any failures with file and line reference.
################################################################################17. Create .claude/commands/security-audit.md:
---description: Run a security audit of all Swift source filesallowed-tools: Read, Bash---Audit all Swift files for:1. Hardcoded API keys, tokens, passwords, or secret-looking UUIDs2. Sensitive data in UserDefaults (use Keychain instead)3. Force unwrapping (!) on values from external sources4. Network calls without certificate pinning (flag, not automatic fail)5. User-facing error messages that expose internal details6. Logging of sensitive data (emails, tokens, personal data)
Output: Critical (fix before TestFlight) / Warning (fix before App Store) / Info (best practice)
################################################################################18. Create .claude/hooks/context-warning.sh:
#!/bin/bashMESSAGE="$1"if echo "$MESSAGE" | grep -qi "context.*threshold\|context.*limit\|context.*capacity\|context.*warning"; then echo "CONTEXT WARNING: Approaching 60% context ceiling." echo "Action: run /compact with a focus instruction, or /clear if between phases."fi
################################################################################19. Create .claude/hooks/stop-sync.sh:
#!/bin/bashbd sync --quiet 2>/dev/null || true
################################################################################20. Create .claude/agents/build-verifier.md:
---name: Build Verifierrole: Verify the Xcode build compiles cleanly and all tests pass on all Simulator targetswhen_to_invoke: Before every commit, before TestFlight uploadoutput_style: Pass/fail with actionable errors---
Read CLAUDE.md to get the scheme name.
Run:xcodebuild build -scheme [SCHEME] -destination 'platform=iOS Simulator,name=iPhone SE (3rd generation)'xcodebuild test -scheme [SCHEME] -destination 'platform=iOS Simulator,name=iPhone 16 Pro Max'
Report: build status, test results (passed/failed count), warnings, specific failures with file+line.Recommendation: ready to commit, or list issues to fix first.
################################################################################21. Create .claude/agents/security-auditor.md:
---name: Security Auditorrole: iOS security vulnerability detection — Keychain vs UserDefaults, ATS exceptions, force unwrapwhen_to_invoke: After each build phase, before TestFlight, before App Store submissionoutput_style: Critical / High / Medium / Low findings with file:line and fix---
Read .claude/rules/security.md and docs/prd/prd.md (non-functional requirements).
Audit all Swift source files. iOS-specific checks:- Sensitive data in UserDefaults (should be Keychain)- ATS exceptions in Info.plist — flag NSAllowsArbitraryLoads- Hardcoded credentials or secret-looking strings- Force unwrapping on values from external sources- Log statements printing personal data, tokens, or internal paths
Format each finding: ### [SEVERITY]: [title] / File: [path:line] / Issue: [desc] / Fix: [action]
################################################################################22. Make hook scripts executable:
chmod +x .claude/hooks/*.sh
################################################################################23. Commit the scaffold:
git add -Agit commit -m "chore: project scaffold — rules, commands, hooks, agents"git push origin main
################################################################################
After creating everything, show the full directory tree so I can do a final verification.Verify the complete scaffold
The complete scaffold should produce this structure:
YourAppName/ ← Xcode source (do not touch) YourAppName.xcodeproj YourAppName/ YourAppNameApp.swift ContentView.swift YourAppNameTests/ YourAppNameUITests/CLAUDE.md ← Claude reads this every session (placeholder version)AGENTS.md ← Team coordination contract.gitignoredocs/ idea/ prd/ adr/ template.md design-system/ agents/.claude/ settings.json rules/ security.md testing.md context-management.md git.md ios-conventions.md agent-teams.md commands/ build-next.md ← Main build loop — run repeatedly build-status.md ← Progress tracker build-polish.md ← Final polish pass create-adr.md run-tests.md security-audit.md hooks/ context-warning.sh stop-sync.sh agents/ build-verifier.md security-auditor.mdWhat the build commands do
These three commands are the entire build operator workflow — you never manually decide what to build next:
- `/build-next` — reads docs/prd/acceptance-checklist.md, finds the first unchecked user story, builds it completely (view, viewmodel, data, error/empty states, tests), ticks the ACs in the checklist, commits. Run this once per user story.
- `/build-status` — shows a progress table across all user stories (ACs done vs total) and tells you what's next. Run anytime.
- `/build-polish` — applies Liquid Glass, spring animations, haptics, and accessibility. Refuses to run if any ACs are still unchecked.
The cycle: /build-status to see the board → /build-next repeated per user story → /build-polish once at the end. See The Build doc for the full workflow.
Next
With the scaffold in place, go to Idea to PRD to start the Idea Pack.
Sign up to read the full guide
Free access to all 12 workflow guides. No password needed.