Beta

Workflows

Dark Factory follows a strict plan-run-merge loop. Each milestone is planned, executed, and merged before the next milestone's implementation begins.

The Development Loop

Every milestone follows the same cycle:

1 Plan
/godark-create-milestone
/godark-create-planning-doc
/godark-create-issues
/godark-create-scenarios
2 Run
godark run --tag phase-N

Agents implement, review, and merge each issue in dependency order.

3 Merge
Rollup PR merges to main

All issue PRs are squashed into the rollup branch, then the rollup merges to main.

After the rollup merges, main has all the milestone's changes. You can now plan and run the next milestone against the updated codebase.

Key rule: Merge the rollup PR before starting godark run for the next milestone. Planning the next milestone (skills 1–4) can happen any time, but implementation must wait for the prior milestone to land on main.

Why this order matters

Each milestone's code is developed against main. If milestone 5 adds a store.Store interface and milestone 6 wires it into the domain layer, milestone 6's agents need milestone 5's code on main to work correctly. Running milestone 6 before milestone 5 merges means agents develop against a stale codebase — the resulting PRs will conflict or silently build on code that doesn't exist in main yet.

Milestone Scoping

A milestone is one coherent unit of work — a feature, a refactor, an integration. How you scope milestones determines whether they can run independently or must be sequential.

Intra-milestone dependencies

Issues within a milestone can depend on each other using Blocked by: #N declarations. The orchestrator resolves these automatically, processing issues in waves:

Wave 1: #10, #11 (no deps)     → implement concurrently → merge
Wave 2: #12 (blocked by #10)   → now unblocked → implement → merge
Wave 3: #13 (blocked by #12)   → now unblocked → implement → merge

This is handled for you — just declare the dependencies in your planning doc and /godark-create-issues writes them into the GitHub issues.

Cross-milestone dependencies

If an issue in milestone 6 references an issue in milestone 5 via Blocked by, those milestones are sequential. The orchestrator only resolves dependencies within a single milestone, so cross-milestone references won't be enforced at runtime — but they signal that the milestones must be run and merged in order.

Watch for this: If your planning doc for phase 6 has issues that say Blocked by: #73 and #73 belongs to phase 5, your milestones are sequential. Run and merge phase 5 first.

Independent milestones

Milestones that touch completely separate code paths — different packages, different services, no shared interfaces — can be run in parallel. This is common when two developers are working on unrelated features in the same repo.

Using --tag

The --tag flag is how you tell godark run which milestone to process:

godark run --tag phase-5

How tag resolution works

--tag phase-5 fetches all milestones from your GitHub repo and matches the tag against milestone titles. A milestone titled "Phase 5: Split Admin API Client" resolves from the tag phase-5. The match uses the phase number extracted from the title prefix.

One milestone per run

Each godark run invocation processes exactly one milestone. To run multiple milestones, run them sequentially:

# Run phase 5, wait for completion and merge, then run phase 6
godark run --tag phase-5
# ... review and merge the rollup PR ...
godark run --tag phase-6

Dry run

Use --dry-run to see the execution plan without processing any issues:

godark run --tag phase-5 --dry-run

This shows which issues are processable, which are blocked, and in what order they would execute.

Common Anti-Patterns

These are real mistakes that break the development loop. Each one produces PRs that are difficult to review, merge, or recover from.

✗ Running multiple sequential milestones without merging

If milestones 5, 6, 7, 8 are sequential (cross-milestone dependencies exist), running all four before merging any of them produces stacked branches. Each PR's diff includes changes from all prior milestones. They can only merge in order, and the diffs are misleading — reviewers see accumulated changes, not the milestone's actual work.

Instead: Run milestone 5, merge the rollup, then run milestone 6, and so on.

✗ Closing issues manually

Issues should close when their PRs merge. Closing them by hand (clicking "Close" in GitHub) breaks the dependency resolver — godark run sees the issue as done and won't process it, but the code was never merged. Downstream issues that depend on it will fail when the code they expect isn't on the branch.

Instead: Let the merge process close issues automatically. If an issue is invalid, label it nodark to skip it.

✗ Opening draft PRs for unmerged milestone chains

Draft PRs for milestones 6, 7, 8 while milestone 5 hasn't merged give the illusion that work is ready for review. In reality, each PR depends on the prior one — they can't be reviewed independently because the diffs overlap and the base code doesn't exist on main yet.

Instead: One milestone at a time. The rollup PR for each milestone is the only PR that needs to exist.

✗ Planning and implementing in the same branch

Running planning skills (create-milestone, create-planning-doc) on a feature branch mixes planning artifacts with implementation code. If the planning commits get shared across branches, multiple PRs end up with identical planning commits in their history.

Instead: Run planning skills on main (or a short-lived planning branch that merges first). Implementation branches should only contain implementation.