Project Setup

Conventions for initializing a new project workspace: creating worktrees, branches, and the initial documentation structure. This is the first step in the project lifecycle — it produces the working environment that all subsequent planning and implementation phases operate in.

Prerequisites

All affected repositories are cloned as siblings under the workspace root (/Users/<user>/code/arda/<repo>).
Git remotes are configured and accessible (git fetch origin succeeds).
The documentation repository is always included — it holds the project’s goal file and artifacts.

Directory Structure

All project work happens in dedicated worktrees under projects/ at the workspace root:

projects/<project-name>-worktrees/
  <repo-1>/              # Worktree for first repository
  <repo-2>/              # Worktree for second repository
  documentation/         # Always present — project docs live here

For multi-agent projects that require parallel work on the same repository, use base + task worktrees with an integration branch:

projects/<project-name>-worktrees/
  <repo>-base/           # Integration worktree
  <repo>-<task-1>/       # Per-task worktree
  <repo>-<task-2>/       # Per-task worktree
  documentation/

Branch Naming

Context	Pattern	Example
Human branch	`<github-user>/<project-name>`	`jmpicnic/multi-pdf-print-and-bugs`
Agent branch	`<github-user>-ag/<project-name>-<repo>-<ticket>`	`jmpicnic-ag/multi-pdf-print-and-bugs-management-519`
Integration branch	`<github-user>/<project-name>/integration`	`jmpicnic/multi-pdf-print-and-bugs/integration`
Task branch (multi-agent)	`<github-user>/<project-name>/<task>`	`jmpicnic/multi-pdf-print-and-bugs/fix-notes`

All branches are created from origin/main to ensure a clean starting point.

Setup Procedure

1. Synchronize Repositories

For each repository that will be part of the project:

Run git fetch origin to get the latest remote state.
Verify the local main branch is not behind origin/main. If it is, pull.
If the repository’s main clone is on a different branch, the worktree can still be created from origin/main directly.

2. Create the Project Directory

mkdir -p projects/<project-name>-worktrees

3. Create Worktrees

For each required repository, create a worktree with the project branch:

# Standard case: main clone is on main
git -C <repo> worktree add \
  /path/to/projects/<project-name>-worktrees/<repo> \
  -b <github-user>/<project-name>

# When main clone is on a different branch: base on origin/main
git -C <repo> worktree add \
  /path/to/projects/<project-name>-worktrees/<repo> \
  -b <github-user>/<project-name> origin/main

For multi-agent setup, create the integration branch first, then task branches from it:

# Integration worktree
git -C <repo> worktree add \
  /path/to/projects/<project-name>-worktrees/<repo>-base \
  -b <github-user>/<project-name>/integration

# Task worktrees (branched from integration)
git -C <repo> worktree add \
  /path/to/projects/<project-name>-worktrees/<repo>-<task> \
  -b <github-user>/<project-name>/<task> <github-user>/<project-name>/integration

4. Verify Each Worktree

Run the appropriate check commands for each worktree to confirm a clean baseline. The specific commands vary by repository type — consult Dev Workflows for the canonical list.

Repository Type	Check Command
Kotlin/Gradle (`operations`, `common-module`)	`make build` (runs `./gradlew build` with coverage)
Documentation (`documentation`)	`make install && make pr-checks`
API Tests (`api-test`)	`npm install && npm run build`
Next.js (`arda-frontend-app`)	`npm install && npm run build`
Storybook (`ux-prototype`)	`npm install && make ci`

Run checks in parallel when possible — they are independent across worktrees.

5. Create the Documentation Working Directory

mkdir -p projects/<project-name>-worktrees/documentation/\
src/content/docs/roadmap/in-progress/<project-name>

6. Create the Goal File

Write a goal.md in the working directory using the Goal Template. The goal file should include:

A summary of the project’s purpose and motivation
Links to all relevant GitHub tickets with inline summaries
The list of affected repositories
Success criteria appropriate to the project’s scale

See the Goal Template for scaling guidance on which sections to include based on project complexity.

Required vs. Optional Repositories

When defining the project, distinguish between:

Required repositories — will definitely have changes; worktrees are created during setup.
Optional repositories — may need changes depending on implementation discoveries; worktrees are created manually if and when needed.

The documentation repository is always required.

Post-Setup

After setup is complete, the project is ready for the next lifecycle phase:

Small projects: Proceed directly to implementation.
Medium projects: Run the Project Planning workflow to produce requirements, specification, and verification documents.
Large projects: Run the Complex Project Definition and Planning workflow for design sessions and iterative planning.