sofa

Agents write the work. Code decides every gate. You approve the intent.

sofa is a software factory inside your agent session. It takes an issue or an idea to a merged change. Agents draft, research, write code and report findings. Code records each fact and refuses any step the facts do not allow. You approve what gets built, answer questions, grant actions and sign waivers.

Watch a run Read how it works

Ledger seal
The ledger seal Drawn from the sha256 of the ledger rows in the run below. Each new row redraws it, and changing any row changes the whole seal. Press Play in the run to watch it.

Request Issue #42: export a report as CSV feature tier, spec 042-csv-export

    At a glance

    From request to merge

    1. A request comes in An issue, a request or an idea starts a run.
    2. You approve the intent You approve the spec, the design and the task plan, grant actions and sign waivers.
    3. Agents build in worktrees Each task gets its own worktree. Agents draft and write code there.
    4. Code checks every gate Code runs the checks and writes each result to the ledger.
    5. Code merges With the merge grant, code merges once the evidence holds. Without it, you merge.

    Why sofa exists

    Agents write code fast, and an agent that writes the code, the tests and the report can grade its own work.

    The problem

    A rule in a prompt does not stop an agent from marking its own work as done. Reviewers also have less time than agents have output.

    The answer

    Code records what happened and refuses any step the recorded facts do not allow. Agents draft, research, write code and report findings, but they never move a gate. Every rule that code can check is checked in code, not left to a prompt.

    Your part

    You approve the spec, the design and the task plan, grant the actions sofa may take, and sign any waiver. A request leaves as merged commits, with a record of why each line exists and how it was proven.

    Who does what

    Code, agents and you each have jobs only that party may do. Most actions belong to exactly one of them.

    Who may do what

    Try thisPick each party in turn and compare the lists.

    Party

      The rules that matter most

        The author never verifies its own work, and the coordinator never writes code. Only you and the gate results that code produces can block. A reviewer writes findings, and a finding blocks only when you promote it.

        All principles
          Every role and what it may not do

          The CLI checks paths, branches and claims on every call. A host hook rejects source writes from the coordinator session and edits outside the active worktree. Where a host cannot tell sessions apart, the rule is only an instruction, and the docs say so.

          What happens in a run

          A request moves from intake to a merged change in up to twelve stages. Each stage leaves a record you can inspect. Most end at a gate that only code or you may close.

          The stages

          Try thisSelect a stage to see what it leaves behind and how its gate closes. Switch the size of the request to see which stages a smaller one skips.

          Sizing tier

            • Code closes the gate
            • You close it
            • Code checks, then you decide
            • No gate

            Where a failed gate sends the work

            A gate that says no sends the work back to the stage that can fix it, with a feedback record that says what failed.

            • Admissionnarrow or clarify, back to intake
            • SPEC, DESIGNyou ask for changes, back to the same stage
            • Verification failswithin the cap, back to waves with feedback
            • Review requests changesa feedback record goes to the affected tasks, back to waves
            • Cap reachedescalation: you choose re-scope, rework or abort

            Safeguards

            These checks stop an agent from passing off its own work as proven. Try the first three here. The ledger runs in the demo at the top.

            Frozen tests

            Once you approve the acceptance tests at the TASKS gate, they are frozen. A verification attempt applies the agent's changes first and your tests on top. If the agent touched a test file, the attempt aborts.

            Try thisPress verify run, attempt 1 once. Then tick the box, so the agent's patch touches a human test, and run it again.

              A changed input makes every command refuse

              task prepare records a digest, a fingerprint, of the task plan. If any input changes later, every command refuses and names the file.

              Try thisPress task start T1 once. Then change one value in the plan, for example a file name, and press it again. Re-approve to fix it, or undo your edit.

              Whitespace does not count, because the digest covers canonical JSON. Any real change does count, and only you can re-approve the plan.

              Grants: what sofa may do without asking

              Grants default to denied. At the TASKS gate you tick the actions sofa may take, and anything you did not grant waits for you.

              Try thisTick a few grants and press Approve. Then try an action you did not grant, and one you did.

              Grants

              Try an action
              • Approving TASKS binds grants.json to the digest of tasks.json. Any change needs a new approval.
              • Force-push, deploy, deleting data and messages outside the repository have no grant. They always wait for you.
              • With merge, code merges one PR through the forge's required checks. An agent never merges.
              • In a real patch or feature run, merge starts ticked and your approval covers the grants as shown. Here every switch starts off so you can try each one.

              The ledger

              Code writes every gate result, verdict, decision and waiver into an append-only ledger.

              The run at the top fills it as it goes. A row appears when a gate closes. The seal is drawn from the sha256 of all rows so far, so changing any row changes the whole seal.

              See the ledger in the run See the seal

              Also enforced

              • Retries are capped. A gate gets three retries per task, or fewer when two attempts in a row fail on the same signal. Then the work escalates to you, and you choose re-scope, rework or abort.
              • Reviewers report findings, and only gate results and you can block. A finding blocks only when you promote it.
              • Code merges once the evidence holds. With the merge grant, code merges when sofa pr watch says READY, the ledger check passes and the review decision is approve, all for the same head. Without the grant, you merge.
              • A verdict belongs to one commit. A push makes a new head that needs a new verdict, and after a rebase a verdict survives only if every commit's patch id is unchanged.

              What it can do

              sofa fits the process to the size of the request: a one-file patch, a typical feature, or a program of parallel tracks.

              1. A patch

                A one-file bug fix with a failing-first test. It skips the SPEC and DESIGN documents but keeps the evidence: a worktree, a proof and an independent verifier. A patch run spawns one worker, so the author and the verifier stay apart.

              2. A feature

                Typical work. Every stage runs except the conditional ones: research runs only when an outside fact is needed, and the prototype only for UI work.

              3. A program

                A big request, such as a migration across several PRs, split into several specs under one coordinator. Each spec is a track that runs the feature pipeline with its own workers and verifiers, side by side.

              Programs. The coordinator reads finished work and questions in batches instead of polling agents. It parks each question in gates.json with its options and a default, so work continues on reversible defaults. Force-push, deploy, deletion and outward messages still wait for a human, and push and merge need their grants. Two limits pause new work: at 70% of the token budget the coordinator stops spawning and asks you, and no more gates wait on you than you can review in a day.

              Ensembles. You can mark a risky task for two or three candidates, each in its own worktree with a different model or strategy. Code keeps the candidate with the best gate results: checks passed, then verifier findings, then diff size. No model picks the winner.

              Atlas, the architecture map

              Atlas draws a C4 map of any repository from its source tree and manifests. It runs no model, so the same commit always gives the same bytes.

              Atlas map

                How atlas fits the pipeline
                • Rules judge the map. Layers, forbidden pairs, cycles, deep imports and a coverage floor are errors and gate results. Unowned files, orphans and fan-out are warnings, so they appear in the review packet and never block by themselves.
                • At DESIGN, the gate shows the current map with the intended changes overlaid, before any code exists. It is the earliest point a human can reject a structural mistake.
                • At TASKS, each intended change is assigned to exactly one task.
                • At task submit, atlas diffs the worktree against the task's base. With enforce: refuse a change DESIGN did not intend refuses the submit. With flag it is recorded for review.
                • In verification, atlas check runs as a step, so the committed outputs must match the integrated target.

                Control plane, every run at once

                Today sofa runs in one repository at a time. A draft proposal adds a control plane: one map of every run across many repositories, built only from the records sofa already keeps.

                Try thisSelect a run to see the facts behind its state. Then run its next action in the terminal below.

                Preview of a draft. The data is made up and nothing here is measured.

                Fleet map

                  The board decides nothing. It reads refs/sofa/* from each repository and can be deleted and rebuilt at any time. Command names and outputs come from the draft and may change.