/init

description: Initialize TandemKit in this project. Sets up the coordination folder, configures roles, installs tools, and verifies Codex access.

TandemKit — Project Initialization

> **Note:** This command is for plugin-based distribution only. For local development, use direct symlinks to the TandemKit repo instead — see README.md for setup instructions.

This command sets up TandemKit in the current project. Run it once per project.

Important UX Rules

Follow these rules throughout the entire init flow:

1. **Do NOT explain what TandemKit is.** The user already knows — they just ran the init command. 2. **Ask questions ONE AT A TIME.** Before each question, write 2-3 sentences of context in chat explaining WHY this matters and what you recommend. Then ask using AskUserQuestion. Never batch multiple questions. 3. **Do NOT install or configure anything without explicit user approval.** Ask first, show what you want to do, get a "yes", then do it. 4. **Before modifying any existing file** (.gitignore, settings.json, config.toml), explain what you want to change and get user approval. 5. **When recommending external tools**, always provide: verified GitHub URL, star count, brief description of what it does, and at least one alternative. Never present a single option as the only choice. 6. **For npm packages, use `npx -y`** (run without global install), never `npm install -g`. Check the user's permission deny list in settings.json — never recommend commands that appear there. 7. **MCP server configurations go in `.mcp.json`** at the project root, NOT in `.claude/settings.json`. MCP tool permissions (allow rules) go in settings.json. 8. **Start brief.** Jump straight to investigation. No preamble, no tutorial. 9. **Before writing any files, show a recap** of all the settings you're about to encode and get user confirmation. This catches misunderstandings before they're baked into config files.

Pre-Flight Check

1. Verify `TandemKit/` does not already exist in the project root. If it does, tell the user: "TandemKit is already initialized in this project. Config is at TandemKit/Config.json." 2. Check that this is a git repository. If not, warn: "This project is not a git repository. TandemKit works best with git for feature branches and milestone commits. Continue anyway?"

Step 1 — Install watchman

Check if watchman is installed: `which watchman-wait`

If not installed, tell the user and wait for approval before installing.

Step 2 — Investigate the Project

Before asking questions, investigate thoroughly. Tell the user: "Let me investigate your project..." then do all of the following:

1. **Read project documentation:**

• `AGENTS.md` or `CLAUDE.md` — conventions, architecture, commit rules
• `README.md` — project overview

2. **Detect project type — check for ALL build systems:**

• `.xcodeproj` or `.xcworkspace` → Apple platform app
• `Package.swift` → Swift package (can coexist with .xcodeproj!)
• `package.json` → Node.js / web
• `pubspec.yaml` → Flutter (may also contain an `android/` + `ios/` folder — treat as multi-platform)
• `build.gradle` / `build.gradle.kts` / `settings.gradle(.kts)` or an `AndroidManifest.xml` → native Android (Kotlin / Java / Compose)
• `Cargo.toml` → Rust / `go.mod` → Go
• **Check submodules:** Read `.gitmodules` if it exists. Check inside submodule directories for build files.
• **If both Package.swift AND .xcodeproj exist:** Note both and present options.
• **If Flutter + `ios/` both exist:** note both — the Android CLI covers the Android side, XcodeBuildMCP covers the iOS side.

3. **Check available tools:**

• Read `~/.claude/settings.json` for global permissions and MCP tool allowances
• Read project `.claude/settings.json` and `.mcp.json` for project-level MCP servers
• Check what's already available: Xcode MCP? browser-use CLI (`which browser-use`)? Simulator tools? Android CLI (`which android`)? Flutter CLI (`which flutter`)?

4. **Read commit conventions and branch patterns:**

• Check AGENTS.md/CLAUDE.md for commit message rules, push policies, branch conventions
• Run `git branch -a` to see existing branch naming patterns — use these for TandemKit feature branches. Do NOT invent a new convention or add prefixes.
• Check for git hooks

5. **Read the user's permission deny list** in settings.json.

6. **Discover existing skills:**

• List `.claude/skills/` contents. Read the name + description of each existing skill.
• Note which skills are relevant for the Generator (e.g., code context, review skills) and Evaluator (e.g., preview patterns, testing approaches).
• Reference these in the role files so roles know to load them.

7. **Explore documentation structure beyond AGENTS.md:**

• Check for research folders, exploration docs, context directories, domain-specific reference material.
• If found, note them for the Planner.md — the Planner needs to know ALL knowledge sources, not just code docs.

8. **Check Codex permissions** (if `~/.codex/config.toml` exists):

• Check if bash/shell commands are allowed (sandbox_mode, approval_policy)
• This determines whether Codex should use CLI or MCP mode for tools

9. **Detect the project name** — used to label session renames so the user can distinguish TandemKit sessions across multiple projects in the session picker:

• Get the git root: `git rev-parse --show-toplevel 2>/dev/null || pwd`
• Take the `basename` of that path as the candidate project name.
• **Generic-folder fallback:** if the basename is one of `App`, `Server`, `Client`, `Frontend`, `Backend`, `Web`, `Mobile`, `iOS`, `macOS`, `Android`, `Desktop`, walk up one level and use the parent's basename instead — these are common umbrella-component folders that are not the project's identity.
• If the resulting name is still ambiguous (parent also generic, or the user has a custom umbrella layout where the meaningful project name lives a level or two up),