Welcome to the Orcs Project! A two-agent horde that builds iOS apps autonomously.

Autonomous iOS App Builders

They don't stop until it's built.

A two-agent horde that builds iOS apps from a project brief. Point them at a target, let them work. Crude but effective.

Powered by: Claude Code and/or OpenAI Codex - configurable per agent. Mix and match models for different roles.

Quick Start

# 1. Clone
git clone https://github.com/youruser/orc
cd orc

# 2. Create your project brief
cp docs/project_template.md docs/project.md
# Edit docs/project.md with your app idea

# 3. Add app artwork to assets/ (optional)
# Put images in assets/ - they get copied to your project

# 4. Summon the horde
cd ..
python orc/summon.py --full-auto

This will:

• Set up camp (YourAppName/ folder)
• Copy battle plans (brand.md, roadmap.md, status.md) and supplies
• Arm the horde with skills (.claude/skills/)
• Unleash the builders

Setup Details

Required: Create project.md

Copy the template and fill it out:

cp docs/project_template.md docs/project.md

Key fields in the frontmatter:

---
name: YourAppName        # App name (creates folder with this name)
platform: ios
team_id: XXXXXXXXXX      # Your Apple Developer Team ID
bundle_id_prefix: com.yourcompany  # For bundle identifier
---

Tip: Use docs/prompt.md with an AI assistant to help generate a comprehensive project.md.

Optional: Add artwork

Put images in assets/ before running. They get copied to your project's assets/ folder.

Tip: Use docs/prompt_generate_assets.md with an image generation tool (ChatGPT/DALL-E, Midjourney, etc.) to create app artwork.

Auto-created folders

These are created automatically on first run:

• drums/ - Horde communication logs
• logs/ - Battle logs

Manual Steps (Owner)

These steps require manual intervention and cannot be automated by the horde:

Before Running Orc (Per Project)

1. Fill out docs/project.md with your app vision
   • Set name, team_id, bundle_id_prefix in frontmatter
   • Describe features, UI, and requirements

During Development (As Needed)

2. Visual QA - Review screenshots, test on real devices
3. Design decisions - Approve UI/UX choices the horde can't make

Before App Store Release

4. Create App ID at developer.apple.com/account

   • Identifiers → App IDs → Register new
   • Use bundle ID: {bundle_id_prefix}.{appname}

5. Create App Store Connect record

   • appstoreconnect.apple.com → My Apps → New App
   • Select your App ID, fill in metadata

For Xcode Cloud CI/CD (Optional but Recommended)

Enables automatic builds when agents push to GitHub:

1. Create GitHub repo for your project

   cd YourAppName
   git init && git add . && git commit -m "initial"
   gh repo create YourAppName --private --push
   

2. Connect Xcode to GitHub (one-time)

   • Xcode → Settings → Accounts → Add GitHub account

3. Create Xcode Cloud workflow

   • Open project in Xcode
   • Menu: Integrate → Create Workflow
   • If prompted "no remote repository": click Add Existing Remote
   • Review workflow settings → Next → Start Build

4. Workflow triggers automatically on push to main

5. Add TestFlight deployment (optional)

   • Integrate → Manage Workflows → double-click your workflow
   • Click + next to Post-Actions in the left sidebar
   • Select TestFlight Internal Testing
   • Choose your tester group → Save

Once configured, the agent workflow becomes:

Agent runs tests locally → pushes to GitHub → Xcode Cloud builds → TestFlight deploy

For Existing Projects

python orc/summon.py --project YourAppName --full-auto

Options

--project NAME        # Work on existing project
--full-auto           # Auto-approve agent actions
--max-turns N         # Limit conversation turns (default: 20)
--resume              # Continue from previous session (reloads context)
--inject "msg"        # Send orders to Taskmaster at start
--list-projects       # Show available projects
--quiet, -q           # Reduce output (only show final responses)
--agents-config PATH  # Use custom warband config (default: orc/config/warband.json)

Structure

orc/                      # The system (this repo)
├── summon.py             # Summon the horde
├── dismiss.py            # Dismiss and clean up
├── config/
│   ├── warband.json      # Horde configuration (model, backend)
│   ├── taskmaster.txt    # Taskmaster instructions
│   └── builder.txt       # Builder instructions
├── templates/            # Copied to new projects
│   ├── brand.md
│   ├── roadmap.md
│   └── status.md
├── assets/               # Your app artwork (copied to projects)
├── docs/
│   ├── project_template.md   # Template - copy to project.md
│   ├── prompt.md             # AI prompt for generating project.md
│   └── prompt_generate_assets.md  # AI prompt for generating artwork
└── .claude/skills/       # Combat techniques

YourAppName/              # Created by orc
├── project.md            # Your battle orders (copied from orc/docs/)
├── brand.md              # Taskmaster fills out
├── roadmap.md            # Taskmaster manages
├── status.md             # Taskmaster tracks progress
├── assets/               # Supplies (copied from orc/assets/)
└── app/                  # Builder constructs here

How It Works

1. You give them orders (docs/project.md)
2. You (optionally) provide supplies (assets/)
3. Taskmaster reads the brief, plans the work, assigns tasks
4. Builder builds, reports back
5. Taskmaster reviews, assigns next task
6. Repeat until the job is done

Cleaning Up

# Clear drums and logs (between sessions)
python orc/dismiss.py

# Full clean (includes state files)
python orc/dismiss.py --all

Prerequisites (One-Time Setup)

Before using orc, complete these steps once on your dev machine:

1. Development Environment

• Xcode 15+ installed from Mac App Store
• Python 3.8+ installed
• Claude CLI installed and authenticated (claude command works)

2. Apple Developer Account

• Enroll in Apple Developer Program ($99/year) at developer.apple.com
• Note your Team ID (found in Membership details)

3. Xcode Signed In

• Open Xcode → Settings → Accounts
• Add your Apple ID (the one linked to your Developer account)
• Verify your team appears under "Teams"

4. GitHub Account (for Xcode Cloud)

• Create a GitHub account if you don't have one
• Authenticate Git on your machine (gh auth login or SSH key)

Without these, orc can build locally but cannot deploy to devices or App Store.

Advanced Configuration

Warband Configuration

Edit config/warband.json to customize your agents:

{
  "pm": {
    "name": "Taskmaster",
    "backend": "claude",
    "model": "sonnet",
    "reasoning_effort": "high",
    "seed": "config/taskmaster.txt"
  },
  "dev": {
    "name": "Builder",
    "backend": "claude",
    "model": "opus",
    "seed": "config/builder.txt"
  }
}

Field	Values	Description
name	Any string	Display name in logs
backend	"claude" or "codex"	Which CLI to use
model	"sonnet", "opus", "haiku", "gpt-5.2-codex", etc.	Model selection
reasoning_effort	"low", "medium", "high", "xhigh"	Extended thinking (Codex/GPT only)
seed	File path	Instructions file for the agent

Example configurations:

# Claude Opus for both (most capable)
"backend": "claude", "model": "opus"

# Mixed: Codex PM + Claude Builder
pm: "backend": "codex", "model": "gpt-5.2-codex"
dev: "backend": "claude", "model": "opus"

# Budget mode with Sonnet
"backend": "claude", "model": "sonnet"

Skills

Skills are automatically injected into agent prompts. Located in .claude/skills/:

• ios-dev - Build commands, TDD workflow, code style, simulator setup
• ios-simulator - Simulator control, screenshots, UI testing, visual QA

To add custom skills:

1. Create folder: .claude/skills/your-skill/
2. Add SKILL.md with YAML frontmatter
3. Skills are shared across all projects

Drums (Communication Logs)

The drums/ directory contains agent communication:

• pm_out.txt / dev_out.txt - Agent responses
• pm_in.txt / dev_in.txt - Input to agents
• *_approvals.txt - Tool approval tracking

Clear with python orc/dismiss.py

State Files

Each project maintains .orchestrator_state.json with session info for --resume:

• Session IDs, turn count, timestamp
• Cleared with python orc/dismiss.py --all

Simulator Auto-Detection

Orc automatically detects an available iPhone 16 simulator and shares its UUID between agents. This prevents commands from spawning duplicate simulator clones.

License

Apache 2.0 + Commons Clause - You can use, modify, and contribute to this project. You cannot sell it or offer it as a paid service. See LICENSE for details.