Teams

How multiple developers coordinate around Dark Factory — milestone ownership, parallel work, and the distributed lock.

Milestone Ownership

One developer (or one godark run process) owns a milestone at a time. This is enforced at two levels:

Planning time: Decide who owns which milestones before running. This is coordination, not tooling — talk to your team.
Runtime: The distributed lock prevents two godark run invocations from processing the same milestone simultaneously.

Ownership means you're responsible for the full loop: run the milestone, review the rollup PR, merge it to main. Don't leave rollup PRs in draft — either merge or abandon them.

Parallel vs Sequential Milestones

Whether two milestones can run at the same time depends on their dependencies.

Parallel Independent milestones

Milestones that touch separate code paths with no shared interfaces, packages, or files. No Blocked by references cross milestone boundaries.

# Developer A                    # Developer B
godark run --tag phase-5         godark run --tag phase-7
# ...merge rollup...             # ...merge rollup...

Both can run simultaneously. Their rollup PRs won't conflict because the changes don't overlap.

Sequential Dependent milestones

Issues in milestone 6 have Blocked by references to issues in milestone 5. The milestones share code paths — milestone 6 builds on interfaces or packages that milestone 5 introduces.

# Developer A runs phase 5, merges rollup
godark run --tag phase-5
# ...merge rollup to main...

# Developer B (or A) runs phase 6 after main is updated
godark run --tag phase-6

Phase 6 must wait for phase 5's rollup to merge. Running them out of order produces stacked branches with overlapping diffs.

How to check

Look at the Blocked by lines in your planning docs or GitHub issues. If any reference crosses a milestone boundary, the milestones are sequential. You can also use godark vet issues --tag phase-N to validate issue structure within a milestone.

Coordination Patterns

Solo developer, multiple milestones

Plan as many milestones as you want up front — running all four planning skills for phases 5, 6, 7, 8 is fine. But run and merge them one at a time:

# Plan everything
/godark-create-milestone    # creates phases 5-8
/godark-create-planning-doc 5
/godark-create-issues 5
/godark-create-scenarios 5
# repeat planning for 6, 7, 8...

# Execute one at a time
godark run --tag phase-5    # run → merge rollup → done
godark run --tag phase-6    # run → merge rollup → done
godark run --tag phase-7    # ...
godark run --tag phase-8

Two developers, independent milestones

Each developer owns their milestones and runs independently. No special coordination needed beyond agreeing on who owns what.

# Alice owns phases 5 and 6 (auth features)
# Bob owns phases 7 and 8 (analytics dashboard)
# No cross-dependencies — they run in parallel

Two developers, sequential milestones

Developer A finishes and merges before Developer B starts. The handoff is the rollup merge to main:

# Alice: phase 5 (adds store interface)
godark run --tag phase-5
# Alice merges rollup PR to main

# Bob: phase 6 (wires store into domain) — can now start
git pull origin main
godark run --tag phase-6

Planning vs execution

Planning skills (create-milestone, create-planning-doc, create-issues, create-scenarios) can run concurrently across developers — they create GitHub issues and write local docs, but don't modify source code. The coordination constraint is on godark run, which creates branches and PRs.

Tip: Run planning skills on main, not on feature branches. This keeps planning artifacts (roadmap files, planning docs) separate from implementation and avoids planning commits showing up in multiple rollup PRs.

The Distributed Lock

When godark run starts, it acquires a lock on the issues it's about to process by applying a label (default: godark:in-progress) to each issue. This prevents a second godark run from processing the same milestone.

What happens on conflict

If another instance is already running against the same milestone, you'll see:

Error: another godark instance is running against this milestone

Clearing stale locks

If a run crashes or is interrupted, the lock may not be released. Use godark unlock to clear it:

godark unlock --repo owner/repo --tag phase-5

This removes the godark:in-progress labels from all issues in the milestone and deletes the local lock file.

Force override

If you're sure no other instance is running, use --force to override the lock:

godark run --tag phase-5 --force

Use this only when you know the previous lock is stale — not to override a teammate's active run.

What the lock does NOT cover

Different milestones: Two developers can run different milestones simultaneously — the lock is per-milestone.
Planning skills: The lock only applies to godark run. Planning skills have no lock because they don't create branches or PRs.
Cross-repo: The lock is scoped to a single repository.