Project Genesis: How a Software Factory Decides to Try Again
Follow a simulated build through planning, deployment status, cost review, and revision. Learn why an agent loop needs explicit state, evidence, and stopping rules.
Writing the code is only the first decision
Imagine asking an agent to create a small application. It produces files and reports a successful build. Then a reviewer spots an unacceptable resource choice. What should happen next: declare the task done, rebuild everything, or revise a specific part and check again?
Project Genesis explores that coordination problem through a software-factory simulation. An architect produces requirements, a coder produces candidate files and deployment outcomes, a FinOps reviewer checks a cost condition, and a supervisor chooses the next action from shared state.
The published Python implementation uses prepared outputs, simulated deployment results, and scenario-driven cost values. This walkthrough follows those functions. It explains the control loop they demonstrate without treating the simulation's elapsed time, cost fields, or success messages as measurements of a real AWS deployment.
Follow a build that needs a second attempt
A candidate is a beginning, not a finish line
Choose a step to see what happens and why it matters.
The architect supplies prepared requirements. The supervisor can then see that the specification stage has produced something for the coder.
This is a simplified view of the state transitions. Indigo specifies the work, teal creates a candidate, amber checks it, and slate represents a recorded outcome. The supervisor mediates the handoffs in the implementation.
Why give the supervisor shared state?
Without an explicit record, “try again” can mean repeating the same action with no memory of why it failed. Genesis instead carries fields such as requirements, candidate changes, deployment status, cost estimate, violations, and history.
The supervisor asks questions about those fields. Are requirements missing? Is there code to work with? Did the simulated deployment fail? Is a cost review still needed? Does an outstanding violation require a revision?
That makes the workflow inspectable. A reader can connect a routing decision to a condition rather than imagining an opaque agent choosing another agent at will.
It also reveals a design responsibility: state fields need precise meanings. In the inspected supervisor, a zero cost estimate is used to signal that a deployment needs auditing. A production design would benefit from representing “not audited” explicitly, so a legitimate zero estimate isn't confused with missing evidence.
What does the local simulation actually do?
The architect returns a prepared pair of requirements. The coder returns a small list of file contents. Its deployment helper returns a success dictionary, or a simulated permission error when the scenario requests one.
The cost-review node likewise selects scenario values. In the budget-spike path it can compare a value of 0.05 with a threshold of 0.04, record a violation, and later report 0.01 after the scripted revision path. These are test values, not cloud prices or billing observations.
That controlled setup has a purpose: it makes a failure reproducible. You can inspect whether a failure causes the right transition before connecting an expensive or consequential external action.
| Simulated component | Question it can help test |
|---|---|
| Prepared requirements | Does the workflow advance after specification? |
| Deployment result | Does failure route to another attempt? |
| Cost condition | Does a violation trigger revision? |
| History and audit state | Does the next attempt remember why it ran? |
A simulator can test decisions about an outcome. It cannot establish that an external operation actually happened.
A cheaper resource is not automatically an equivalent application
The FinOps helper proposes instructions such as replacing an RDS instance with DynamoDB or reducing a function's memory allocation. Those are examples of proposed revisions in the source.
Whether a change is appropriate depends on the application's data model, access patterns, performance requirements, and migration plan. A cost condition is one constraint among several. Satisfying it by breaking the application's behavior would not be a successful repair.
Pause and predict: if the cost field falls after a revision, has the refactor been verified?
Only the observed cost condition has changed. You still need to establish that the new design preserves required behavior and that its cost estimate came from a valid source. In this simulation, the values are scenario-driven, so the falling number demonstrates a branch through the workflow rather than a measured saving.
This is a useful general rule for agent systems: a local success signal should not silently stand in for a broader objective.
Approval is another state transition, not a line of narration
Genesis includes an approval helper for high-risk actions. Its inspected implementation prints an approval message and returns true. That is a simulation of the intended interaction, not a real wait for a person's decision.
A working approval boundary would need to record the specific proposed action, pause before executing it, and resume only after a decision associated with that action. A refusal or an expired request needs a defined outcome too.
Automatic checks are useful for narrow, reversible candidate changes. Actions that affect an existing deployment require a clear authority model. Naming a step “approval” doesn't establish that a person actually reviewed or authorized it.
What the logs can prove
A timestamped event log helps reconstruct a run: which function was called, what state changed, and which scenario branch executed. That is useful evidence about the simulator's behavior.
It is not automatically evidence of deployment to AWS, a real Cost Explorer query, or measured production savings. The implementation needs to attach external confirmation to those claims before the report can make them.
The repository includes deployment-oriented scaffolding as well as local SDK fallbacks. Those are integration starting points. Their presence doesn't change the origin of the simulation results described here.
How would you move beyond the simulation?
Keep the state contract, then replace one simulated boundary at a time. Validate generated files in an isolated environment. Record the confirmed outcome of an external deployment. Give cost observations a source, time window, and interpretation. Enforce retry limits and a terminal failure path when a revision cannot satisfy the constraints.
Test denial as carefully as approval, and failed verification as carefully as success. The repository's scenario tests are useful places to express routing expectations; this walkthrough reviews their role without claiming to have executed a cloud integration test.
Genesis's transferable idea is the feedback loop. A candidate, a checked outcome, and a completed task are different states. A software factory becomes easier to trust when it shows exactly why it is advancing, retrying, or stopping.
Explore the implementation
Source reviewed at revision 74eb0d8: