Skip to content

Instantly share code, notes, and snippets.

@mikegehard

mikegehard/README.md

Created January 22, 2026 17:41
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save mikegehard/1385345f81c26458f311356fd9bfeefa to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save mikegehard/1385345f81c26458f311356fd9bfeefa to your computer and use it in GitHub Desktop.
Download ZIP
AI-native software factory with the Phoenix Architecture
Raw
README.md

Software Factory

Purpose (Why)

To create a highly automated software factory (factory) that can build other software systems (system) to the same quality as a whole principal level, agile balanced team (product, design, engineering).

The idea end state of this factory is The Phoenix Architecture.

Implementation (What)

The Phoenix Architecture seeks to create specifications for a software system that allow parts of the systems to be regenerated.

Specifications MUST be used to define current state, delta and desired state used below.

This project will use IETF RFC2119 guidance to create clear, unambiguous standards: - MUST (absolute requirement) - SHOULD (recommended but optional with consequences) - MAY (optional permission) - "MUST NOT," "SHOULD NOT,", "MAY NOT, indicating prohibitions - Reasoning MUST be provided when SHOULD or MAY are followed

Factory:

  • MUST itegrate ideas from Toyota Production System as an example of a process that focuses on quality

  • MUST be able to represent current state as specifically as possible.

    Example of a current state:

    • system is running in production

  • MUST be able to represent a requested change to current state as a delta

    Examples:

    • system MUST respond 100 ms faster
    • Sign in button MUST change to blue

  • MUST be able to self correct incrementally to move to the desired state through closed feedback loops.

    Definition: desired state == current state + delta.

    Examples:

    • system running in production responds 100 ms faster
    • system running in production with blue button

  • MUST minimize the difference between representation of state and actual value of state

    Notes:

    • Any delta between the representation of state and the actual value of the state will cause a difference in the current state and the desired state.

    • Any incremental progress is good. Examples: - A reviewable PR is progress. - A partial implementation with tests is progress. - The only failure is a step that doesn't push the system towards desired state at all. - Small, frequent commits beat large, infrequent ones.

  • MUST provide an way (checks) to reduce the delta between current state and desired state to as close to zero as possible for each closed feedback loop

    • Deterministic checks:

      • MUST return 0 for success or 1 for failure

      • MUST provide detailed feedback of why check failed to guide current state towards desired state as few steps as possible

      • Examples:

        • linting
        • compiler
        • tests
          • user facing, e2e
          • code facing, unit functional
        • SAST/DAST
        • security scanning

    • Non-deterministic checks

      • Examples:
        • human review
        • LLM judgment

  • MUST work to increase the levels of automation while keeping quality high to speed up time from story -> production

    NOTES:

    • Human in the loop allows for reinfement of agent behavior
    • Trust in agent behavior is necessary to increase the amount of automation through agents
    • Humans set the direction and approve the results.
    • Agents SHOULD never make decisions that require human judgment — they MUST ask a human when unclear about direction until trust is gained

  • Examples of closed feedback loops applied to a software systems:

    • inner loop (story → code/tests → commit on green -> push to PR)
    • outer loop (PR -> CI -> production)

      • CI is the source of truth If tests pass, the code can ship. If tests fail, the code doesn't ship.

        Agents are forbidden from weakening CI to make their work pass. No skipping tests, no reducing coverage requirements, no "temporary" workarounds. If an agent can't pass CI, it asks for help or tries a different approach.

Interface between the factory and the system being built:

Factory:

  • MUST only change code in the directory system-under-construction
    • this is the code of the system being built by the factory
  • MUST be able to load an agent context window with context about the system being built

System being built:

  • MUST provide a README.md at the root of the codebase as way for the factory to gather context about the system.
  • MUST provide a project-container at the root of the codebase that the factory will use as the development environment for the system

References

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment