Project Structure

How meta-loop artifacts fit into an iOS/SwiftUI Xcode project. Covers directory layout, who creates each file, and what belongs in the Xcode project navigator.

Directory Layout

MyApp/                              # Git repo root
├── MyApp.xcodeproj                 # Xcode project (you create)
├── MyApp/                          # Swift source (you + AI create)
│   ├── MyAppApp.swift
│   ├── ContentView.swift
│   └── Views/
│       └── FeatureView.swift
├── MyAppTests/                     # Test source (you + AI create)
├── CLAUDE.md                       # AI agent file (ml-setup creates, you maintain)
├── PROJECT-NOTES.md                # Session notes (ml-setup creates, you maintain)
├── PROJECT-TODO.md                 # Task tracking (ml-setup creates, you maintain)
├── README.md                       # Project readme (ml-setup creates, you maintain)
├── .claude/                        # Claude Code config (install.sh creates)
│   ├── commands/                   # Slash commands
│   │   ├── ml-setup.md
│   │   ├── ml-wireframe.md
│   │   ├── ml-spec.md
│   │   ├── ml-impl.md
│   │   └── ml-retain.md
│   ├── skills/                     # Reference docs
│   │   ├── meta-loop-methodology/
│   │   │   ├── SKILL.md
│   │   │   └── meta-loop-diagram.png
│   │   ├── wireframe-design/
│   │   │   └── SKILL.md
│   │   ├── view-specifications/
│   │   │   └── SKILL.md
│   │   └── project-structure/
│   │       └── SKILL.md
│   └── settings.json               # MCP servers, permissions (you create)
├── specs/                          # Specifications (ml-setup creates dir)
│   └── views/                      # View specs
│       └── feature-name/           # One directory per feature
│           ├── *-wireframe.png     # You create (drawing tool, one or more)
│           ├── about-this-view.md  # You create (optional context)
│           ├── spec.md             # ml-spec generates
│           └── notes.md            # ml-spec generates, you + AI update
├── supporting-docs/                # App-level context (ml-setup creates dir)
│   └── about-this-app.md          # You create
└── doc/                            # Retained learnings (ml-retain creates dir)
    ├── SHARED-PATTERNS.md          # ml-retain generates (optional)
    └── DECISIONS.md                # ml-retain generates (optional)

File Responsibility Matrix

File / Directory	Created By	Maintained By	In Xcode Project?	Purpose
MyApp.xcodeproj	You (Xcode)	You / Xcode	—	Xcode project file
MyApp/ (Swift source)	You + AI	You + AI	Yes	App source code
MyAppTests/	You + AI	You + AI	Yes	Test source code
CLAUDE.md	/ml-setup	You	No	AI agent context file
PROJECT-NOTES.md	/ml-setup	You	No	Session notes and observations
PROJECT-TODO.md	/ml-setup	You + AI	No	Task tracking
README.md	/ml-setup	You	No	Project readme
.claude/commands/	install.sh	Plugin updates	No	Slash command definitions
.claude/skills/	install.sh	Plugin updates	No	Reference skill documents
.claude/settings.json	You	You	No	MCP servers, permissions
specs/views/	/ml-setup	—	No	Parent directory for view specs
specs/views/*/*-wireframe.png	You	You	No	Hand-drawn wireframe images (screen and/or logic)
specs/views/*/spec.md	/ml-spec	AI (regenerated)	No	Generated view specification
specs/views/*/notes.md	/ml-spec	You + AI	No	Decisions and context per feature
specs/views/*/about-this-view.md	You	You	No	Optional extra context for a view
supporting-docs/	/ml-setup	—	No	Parent directory for app context
supporting-docs/about-this-app.md	You	You	No	App purpose, audience, features
doc/	/ml-retain	AI (on demand)	No	Retained learnings
doc/SHARED-PATTERNS.md	/ml-retain	AI	No	Cross-feature patterns (optional)
doc/DECISIONS.md	/ml-retain	AI	No	Architectural decisions (optional)

Xcode Integration

Only Swift/asset source goes into the Xcode project navigator. Everything else lives in the repo but outside Xcode's project references.

In Xcode project (managed by Xcode)

• MyApp/ — Swift source, assets, Info.plist
• MyAppTests/ — Test source

In repo, outside Xcode project

• specs/ — Wireframes and specifications
• supporting-docs/ — App context documents
• doc/ — Retained learnings
• .claude/ — Commands, skills, settings
• CLAUDE.md, PROJECT-NOTES.md, PROJECT-TODO.md

Xcode ignores files that aren't added to the project navigator. No special configuration is needed — just don't drag the meta-loop directories into Xcode.

.gitignore Guidance

Track all meta-loop artifacts in git. Specs, wireframes, supporting docs, and retained learnings are the persistent value of the meta-loop process. Code can be regenerated from them; they cannot be regenerated from code.

Your .gitignore should exclude only standard Xcode/macOS build artifacts:

# Xcode
build/
DerivedData/
*.xcuserdata
*.xcworkspace/xcuserdata/

# macOS
.DS_Store

# Swift Package Manager
.build/

Do not gitignore:

• specs/ — These are your source of truth
• supporting-docs/ — Context that drives spec generation
• doc/ — Retained learnings from past sessions
• .claude/ — Commands and skills needed by every collaborator
• CLAUDE.md — Shared AI context for the project

Directory Creation

Directory	Created By	When
.claude/commands/	install.sh	Plugin installation
.claude/skills/	install.sh	Plugin installation
specs/views/	/ml-setup	Project scaffolding
supporting-docs/	/ml-setup	Project scaffolding
doc/	/ml-retain	First learning retention session

You create feature subdirectories (e.g., specs/views/bookmarks/) manually when you save your wireframes.

Optional Files

These files are not created by any command but can add useful context:

File	Purpose	Who Reads It
specs/views/*/about-this-view.md	Extra context for a specific view (design rationale, edge cases)	/ml-spec, /ml-impl
doc/SHARED-PATTERNS.md	Patterns that apply across multiple features	/ml-impl via CLAUDE.md reference
doc/DECISIONS.md	Architectural decisions with rationale	/ml-impl via CLAUDE.md reference