cd ~/workspace/YourAppName

git init
git checkout -b main

# Proper iOS .gitignore
curl -o .gitignore https://raw.githubusercontent.com/github/gitignore/main/Swift.gitignore

# Append common extras
cat >> .gitignore << 'EOF'

# macOS
.DS_Store
*.DS_Store

# Xcode user state (never commit)
*.xcuserstate
xcuserdata/
*.xcscmblueprint

# Derived data and archives
DerivedData/
*.ipa
*.xcarchive

# SPM build artefacts
.build/
.swiftpm/

# Claude Code local state
.claude/settings.local.json
EOF

git add .gitignore
git commit -m "chore: initialise iOS project with .gitignore"

# Push to GitHub (creates private repo)
gh repo create YourAppName --private --source=. --push

cd ~/workspace/YourAppName
claude

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.md
docs/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 Phase
Scaffold — 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 Patterns
Pattern 1 — Feature Squad: UI agent + Data agent + Test agent
Pattern 2 — Research Debate: two agents argue approaches, lead decides
Pattern 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]

## Context
What is the issue or question?

## Decision
What was decided?

## Consequences
Positive, negative, and neutral consequences.

## Alternatives considered
What 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.

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 ACs
allowed-tools: Read, Write, Bash
---

You are the build controller. Build exactly ONE user story, completely, then stop.

## Step 1: Read project context
Read 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 story
Find 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 story
Read 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: Tests
Write @Test functions in [AppName]Tests/ for ViewModel state transitions and business logic.

## Step 5: Build and test
xcodebuild 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 checklist
In docs/prd/acceptance-checklist.md:
- [ ] AC-00X.Y → - [x] AC-00X.Y for every implemented AC
If an AC is blocked (backend/device only): leave unchecked, add <!-- blocked: reason -->

## Step 7: Commit
git 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 next
allowed-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 checked
allowed-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 errors
xcodebuild test → fix all failures
git 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 Record
allowed-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 targets
allowed-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 files
allowed-tools: Read, Bash
---
Audit all Swift files for:
1. Hardcoded API keys, tokens, passwords, or secret-looking UUIDs
2. Sensitive data in UserDefaults (use Keychain instead)
3. Force unwrapping (!) on values from external sources
4. Network calls without certificate pinning (flag, not automatic fail)
5. User-facing error messages that expose internal details
6. 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/bash
MESSAGE="$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/bash
bd sync --quiet 2>/dev/null || true

################################################################################
20. Create .claude/agents/build-verifier.md:

---
name: Build Verifier
role: Verify the Xcode build compiles cleanly and all tests pass on all Simulator targets
when_to_invoke: Before every commit, before TestFlight upload
output_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 Auditor
role: iOS security vulnerability detection — Keychain vs UserDefaults, ATS exceptions, force unwrap
when_to_invoke: After each build phase, before TestFlight, before App Store submission
output_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 -A
git 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.

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
.gitignore
docs/
  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.md