Skip to content

system-flow.md

Latest commit

 

History

History
175 lines (137 loc) · 8.09 KB

system-flow.md

File metadata and controls

175 lines (137 loc) · 8.09 KB
Raw

Dark Factory Execution Flow

This document is the agent-readable execution contract for Dark Factory. See the interactive system flow for the human visual.

Ownership

Component Responsibility
Planning folder Stores durable project context, the Task Graph, and dependencies.
Dark Factory skill Teaches an operator agent how to start, monitor, recover, stop, and clean a run.
Dark Factory controller Selects tasks, enforces run limits, supervises delivery, orders merges, reconciles state, and coordinates cleanup.
Agent Orchestrator Creates or restores Codex workers, isolated worktrees, processes, and runtime state.
Archon Runs the repeatable workflows inside each feature worktree.
GitHub Provides pull request, review, CI, mergeability, and merge truth.

The controller must not edit feature worktrees. Feature changes belong to the assigned Agent Orchestrator worker running Archon.

Start

  1. A human in a Codex session asks the agent to use the Dark Factory skill.
  2. The skill inspects the target project and its planning folder.
  3. The planning folder provides project context and the Task Graph.
  4. The skill starts the controller with the requested limits and monitors it until the run finishes, stops, or reaches a real recovery boundary.

Controller Loop

Dark Factory repeats this loop while work remains:

  1. Read the Task Graph and runtime state.
  2. Choose runnable tasks within the active run limits.
  3. Start or resume the selected work through Agent Orchestrator.
  4. Observe worker, Archon, pull request, and process evidence.
  5. Route ready pull requests through the ordered merge queue.
  6. Re-read project state after every merge or recovery transition.

A task is runnable only when its Task Graph dependencies are complete and it is not already active, completed, or blocked. Agent Orchestrator creates one Codex worker and one isolated worktree for each selected feature. Multiple features may run independently up to the concurrency limit.

Per-Feature Lifecycle

Every selected feature follows the same lifecycle inside its assigned worktree.

auto-feature Archon workflow

  1. Start infrastructure with wtc.
  2. Start the project servers with the dev-start helper.
  3. Plan the selected task with superpowers:writing-plans.
  4. Implement and validate with superpowers:subagent-driven-development.
  5. Run frontend QA with vercel-browser when the task affects frontend behavior.
  6. Mark the task complete in the feature branch Task Graph.
  7. Commit the completed feature with commit.
  8. Open the pull request with ship.

The workflow then stops. The Agent Orchestrator worker invokes auto-merge in prepare mode after auto-feature finishes.

The task remains [ ] on main until its pull request merges. The feature branch must contain the same task marked [x] before it can enter the merge queue.

auto-merge custom skill

auto-merge owns the review-to-merge readiness loop. The caller selects its mode:

Caller Mode Result when merge-gate confirms readiness
Agent Orchestrator worker prepare Publish readiness evidence and hand the pull request to Dark Factory.
Dark Factory merge queue finalize Merge the pull request on GitHub.

Both modes run auto-squash and then merge-gate. A retry returns to auto-squash; it does not restart auto-feature.

auto-squash skill loop

  1. Wait for a 5-minute quiet window.
  2. Run the auto-squash Archon workflow.
  3. Check review comments and CI status.
  4. If nothing needs work, leave the loop and enter merge-gate.
  5. If work remains:
    • Scan the pull request with pr-scan.
    • Fix and validate the findings.
    • Commit and push the fixes with commit.
    • Resolve review threads with pr-resolve.
    • Repeat from the quiet-window wait.

merge-gate Archon workflow

The gate first checks CI, reviews, branch freshness, and mergeability.

State Action Next state
Ready Confirm readiness. Apply the caller-selected prepare or finalize result.
Not green Return to auto-squash for review or CI repair. Retry the outer auto-merge loop.
Pending Wait for required pull request checks. Recheck readiness.
Stale Update the branch. Wait for pull request readiness, then run the final readiness check.
Conflict Resolve conflicts with fix-merge-conflicts. Continue through conflict validation.
Unsafe Preserve the workspace and stop for recovery. Blocked.
Repair failure Preserve the workspace and stop for recovery. Blocked.

Conflict validation follows these steps:

  1. Determine whether the conflict repair affects frontend behavior.
  2. Run browser QA with vercel-browser when frontend behavior is affected.
  3. Commit and push the conflict repair.
  4. Wait until the pull request is ready.
  5. Run the final readiness check.

The final readiness check routes ready work to the caller-selected mode, review or pending work back to the outer auto-merge loop, and unsafe or failed work to recovery.

Merge Queue

Dark Factory owns the merge queue. It processes one candidate at a time so each pull request is checked against the latest main branch.

  1. Collect eligible pull requests. Rebuild the queue after every merge.
  2. Order candidates by task priority, then task ID.
  3. Verify the next candidate:
    • Confirm the assigned worker completed the task.
    • Confirm CI is green, the branch is fresh, and the pull request is mergeable.
    • Confirm the task is [ ] on main and [x] in the candidate pull request.
  4. Route the candidate:
    • Ready: finalize the candidate through auto-merge.
    • Recoverable: refresh its recorded pull request state or restore its worker and resume auto-merge, then verify the same candidate again.
    • Unsafe: preserve the queue and workspace, then stop for recovery.
  5. In finalize mode, merge-gate performs its final safety check and auto-merge merges the pull request on GitHub.
  6. Update project state:
    • Mark the Agent Orchestrator session as merged.
    • Refresh the main checkout.
    • Re-read the Task Graph.
  7. Clean only the feature that just merged:
    • development processes;
    • temporary browser data;
    • Docker resources and volumes;
    • local feature branch;
    • worktree;
    • Agent Orchestrator session.
  8. If cleanup fails, stop the queue and retry cleanup during recovery.
  9. If queued pull requests remain, rebuild and reorder the queue before checking the next candidate.
  10. If the queue is empty, re-evaluate the Task Graph and runtime state.

Recovery Rules

Condition Recovery action Resume point
A newer commit was pushed after readiness was recorded. Refresh the saved pull request state. Verify the same merge candidate again.
auto-merge stopped before preparation finished. Restore the same Agent Orchestrator worker and resume auto-merge. Verify the same merge candidate after fresh readiness evidence is published.
A repairable review, CI, stale-branch, or conflict condition remains. Resume the owning worker and let auto-merge run the required repair path. Re-enter the merge queue with fresh evidence.
The pull request, worker handoff, or Task Graph is unsafe or inconsistent. Preserve the workspace and stop. Resume only after the unsafe state is resolved.
Per-feature cleanup failed. Keep the queue stopped and retry cleanup. Continue with the next candidate only after cleanup succeeds.

Recovery restores existing work. It must not create a fresh feature for a pull request that already has an owning worker or worktree.

Run Completion

After the queue is empty, Dark Factory re-reads the Task Graph and runtime state:

Result Action
Runnable or active work remains Return to the controller loop and continue within the active run limits.
Every planned task is complete Finish the run.
State requires recovery Preserve state and stop for recovery.

The run is complete only when all planned tasks are complete and no managed feature still requires scheduling, merge processing, recovery, or cleanup.