How I run a software house made of AI agents

Written by Guilherme · Reviewed by an intelligent agent

6 min read

I am a software engineer with 7 years of experience, and I run a software house where almost all of the work is done by AI agents. I decide what gets built, I review it, and I am the only one who merges into main. This post explains how that works and how the website you are reading became the proof that it could.

Nearly everything below comes from the organization’s repositories on GitHub; where it comes from me instead, I say so. Counts are as of 31 October 2026, and times are UTC.

The idea: small contexts, everything written down

An agent works better with a short, focused context, so I do not keep long conversations alive. A session starts with an empty context, loads its role, takes one task and reads only what that task needs. When the session gets heavy, I replace it with a fresh one. The rule that makes this possible is in the shared handbook: anything a future session needs must be written on GitHub before the session ends. Decisions and rules go in the handbook, progress goes in ticket comments, code and tests go in pull requests, and the product owner (PO) agent keeps its working state in a notes file.

That is what I mean by “GitHub is the memory”. It is a design choice, and I think it is cheaper and easier to audit than one long chat. That is my opinion; I have not measured the cost.

The team

The house has five kinds of participant:

  • Me, the owner. I bring the ideas, answer questions, review and merge.
  • The PO agent. It interviews me, turns an idea into small tickets, and keeps the backlog and the handbook honest.
  • The design agent. It works with me on visual identity and page designs, and leaves design documents.
  • Development agents. Two of them work the queue, one ticket at a time, with tests and documentation.
  • The writer agent. It helps me write these posts. It works from the repositories and from my interview with the PO, I decide what is said, and it does what I ask and assists me.

Each agent has its own git identity and a label on its pull requests, so the history shows who did what. The pull requests are opened from my GitHub account, which means that GitHub’s “merged by” field shows my name even for the merges an agent performs under my token. The agent label is the reliable signal.

How a ticket moves

Work moves across a project board with eight statuses, and each status has exactly one party that must act next: Backlog, Refining, Awaiting Input, Queue, In Progress, Dev Blocked, In Review and Done.

The status that matters most is Queue. A ticket in the queue is an approved specification, and that is what lets agents work without asking me each time. The agent that refines a ticket decides when it is ready, using a written checklist: testable acceptance criteria, a size of S or M, no open question that only I can answer, and no secret or paid service needed. If I have to answer something, the ticket goes to Awaiting Input with one clear question.

A development agent claims a ticket by creating a lock branch, which GitHub accepts only once, so two agents cannot take the same ticket. It works on its own branch, opens a pull request and waits for the checks: unit tests, end-to-end tests, Lighthouse and secret scanning. If a check fails, it fixes it. After 3 failed attempts on the same failure it stops and marks the ticket Dev Blocked. A ticket that stays In Progress for more than 24 hours is inspected by the PO.

For bigger work there are epics, which have an integration branch. The sub-ticket pull requests are merged into that branch by the development agents once the checks are green, and I review the whole epic in one pull request into main.

The proof of concept: the website

The first product was this site. The repository was created on 30 October 2026 at 04:39. The epic with the whole MVP (the Home, About and Contact pages in English and Portuguese, plus the deploy workflow) was merged into main at 15:28, which is 10 hours and 49 minutes later, measured from the repository creation to the merge of the epic pull request.

Nine pull requests were merged into the epic branch. Eight of them were merged between 4 and 11 minutes after they were opened, which I measured from the opening and merge timestamps. The ninth, the design of the Home page, waited 7 hours and 1 minute for my review. The agents were not the slowest step; the review was, because I was asleep during that interval. The agents kept working and waiting for my review. That detail comes from me, not from GitHub, which only shows when the pull request was opened and merged. I take it as a fair description of the arrangement, since the review is the part I decided to keep.

What the house is not

It is not fully automated. I write the direction, answer the questions agents cannot answer, review every change that reaches main, and decide what is good enough. It is not free of mistakes either. The house exists to make the work visible, so mistakes can be seen and fixed in the open.

At the time of writing, the four repositories that hold the house and the first product (the handbook, the project template, the website and the organization profile) had 53 merged pull requests and 40 closed issues between them. I counted them with the GitHub API on 31 October 2026, and I left out the PO’s private notes repository.

I wrote this post with the help of the writer agent, which worked from the repositories and from my interview with the PO. I directed what it says, and I review it and merge it myself. The next posts will each tell the story of one project, starting from its own repository.