# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What This Repository Is

This is a **workflow template** for building App Store-ready iOS/macOS applications using Xcode and Claude Code. The core artifact is [PROMPT.md](PROMPT.md) — a structured, 8-phase methodology prompt that guides Claude Code through transforming existing code (prototype, partial app, web logic) into a production-quality Apple platform application.

Use this repo by copying or referencing `PROMPT.md` as a system/task prompt when starting a new Xcode project with Claude Code.

## Workflow Phases (defined in PROMPT.md)

| Phase | Name | Key Gate |
|-------|------|----------|
| 0 | Codebase Intake & Audit | Full read of target folder; audit report approved before any code |
| 1 | Architecture & Project Setup | Architecture pattern, Xcode scaffold, SwiftLint; confirmed before Phase 2 |
| 2 | Core Feature Implementation | One feature at a time; build must pass after each feature |
| 3 | Data, Persistence & Networking | async/await only; secrets in Keychain |
| 4 | Accessibility & Localization | Accessibility Inspector sign-off required |
| 5 | Performance & Quality | Instruments profiling; >=70% test coverage; all tests pass |
| 6 | App Store Preparation | Archive + TestFlight validation |
| 7 | Handoff Documentation | SETUP.md, CHANGELOG.md, ARCHITECTURE.md |

## Core Constraints

- **Never skip or combine phases** without explicit user approval.
- **Never mark a phase complete** if there are compiler errors, warnings, or failing tests.
- **Always show a summary** of what you're about to do and wait for approval before acting.
- **Stop and ask** when encountering ambiguity — never assume and proceed.

## Technology Defaults

- **Language**: Swift, **UI**: SwiftUI, **Concurrency**: async/await
- **Persistence**: SwiftData, **Secrets**: Keychain only
- **Colors**: Semantic assets only, **Typography**: Dynamic Type
- **Touch targets**: 44x44pt minimum
- **Build target**: Latest stable Xcode + iOS/macOS SDK

## Example Project

This workflow was used to build [SoliCards-iOS-iPadOS-MacOS](https://git.istratai.cloud/aj/SoliCards-iOS-iPadOS-MacOS) — a native SwiftUI solitaire game ported from a web-based JavaScript app.