SISF Self-improvement
Software Factory
GitHub

REV P0Design complete. Go implementation of P0–P3 in progress. Nothing released yet.

Free and open source · Apache-2.0 · From the creator of AgentKit.best

Software is solved. Here is the drawing.

A free, open-source software factory, specified as one deployment. A GitHub issue goes in; agents write the fix, an independent QA gate signs it off, and a trusted supervisor ships it by canary and rolls it back on its own. The drawing is finished. The build has started.

Star on GitHub Get started

In development, not available yet. Dotted outline = not built yet.

01 · How it works

Run the line.

Fifteen states, from a labelled issue to a verified release. Watch a pass, step through it, or inject a canary fault and watch the rollback. This is the lifecycle as designed in the brief (§5.2), not a recording of running software.

Schematic of one SISF factory: three zones and the line an issue travels A GitHub issue labelled sisf:ready enters the factory boundary. In Zone 3, the control plane, it is taken in and scoped, and new features wait at an Owner gate. In Zone 2, the agent factory, a coding agent writes the fix and a separate QA gate grades it; a failure goes back for retry. The trusted supervisor in Zone 3, which agents cannot write to, receives the release candidate and releases it into Zone 1, the application, by canary at 5, 25 and then 100 percent. A monitor checks the revision that is actually running; only then is the issue closed on GitHub. If errors cross the threshold, the supervisor rolls back to the last known good release and the issue is blocked with evidence. Values marked with an asterisk are starting points, to be calibrated. GITHUB source of truth, outside the factory Z3 CONTROL PLANE Z2 AGENT FACTORY Z1 APPLICATION FACTORY BOUNDARY · ONE DEPLOYMENT · factory_id IN OUT CONTROL SURFACES Dashboard · API · CLI · MCP · WebMCP AGENT RUNTIMES Claude CLI · Codex · Pi (built-in) APPLICATION · SERVES THE VERIFIED REVISION Webapp · API · MCP · WebMCP — emits traces, logs, sessions and feedback fail → retry ROLLBACK · 5xx > 2%* NEW ISSUElabel sisf:ready 1 INTAKEscope + DoD 2 OWNER GATEnew features 3 CODING AGENTwrites the fix 4 QA GATE85/100* + gates 5 SUPERVISORtrusted · LKG 6 TRUSTED BOUNDARY no agent write access CANARY5 → 25 → 100%* 7 MONITORobserved DoD 8 ISSUE CLOSEDwhen verified 9 qa_receipt · signed BLOCKED · EVIDENCE LKG RESTORED PRELIMINARY DESIGN COMPLETE · BUILD IN PROGRESS ONE DEPLOYMENT · THREE ZONES · ONE LIFECYCLE · 15 STATES Schematic of one SISF factory: three zones and the line an issue travels GITHUB source of truth, outside the factory Z3CONTROL PLANE Z2AGENT FACTORY Z1APPLICATION FACTORY BOUNDARY · factory_id AUTO-ROLLBACK if 5xx > 2%* NEW ISSUEsisf:ready INTAKEscope + DoD OWNER GATEnew features AGENTwrites a fix QA GATE85* + gates SUPERVISORtrusted · LKG TRUSTED agents cannot write here CANARY5→25→100%* MONITORobserved DoD CLOSEDwhen verified qa_receipt signed LKG RESTORED BLOCKED PRELIMINARY DESIGN COMPLETE · BUILD IN PROGRESS ONE DEPLOYMENT · 3 ZONES · 15 STATES
State Intake → Closed 15 states

A labelled GitHub issue is scoped, built by one agent, graded by another, released by canary, and closed only after the running revision meets its Definition of Done. The full schedule of states is listed below.

A fault applies at the next canary. Keyboard: focus the drawing, then ← → to step, Space to play or pause, F for a fault, Home to restart.

Project
SISF · Self-improvement Software Factory
Dwg no.
SISF-001
Status
Preliminary. Design complete. Go implementation of P0–P3 in progress. Nothing released yet.
Rev
P0
License
Apache-2.0, free
Drawn by
AgentKit.best
Notes
  • main line
  • conditional path
  • planned, not built yet
  • factory boundary
  • * starting value, to be calibrated

State schedule

15 states and their transitions · brief §5.2
  1. 01IntakeZ3 · Control plane

    A labelled issue arrives through a signed webhook or reconciliation and is recorded exactly once. The label asks for work; it grants no permission.

    Next: Clarifying if information is missing, otherwise ScopeDraft.

  2. 02ClarifyingZ3 · Control plane

    The factory asks its questions in one comment that it keeps updating. No answer before the timeout means needs-info, not endless spending.

    Next: ScopeDraft once the answer is complete.

  3. 03ScopeDraftZ3 · Control plane

    A versioned Scope of Work and Definition of Done are attached to the issue. A significant edit after approval invalidates that approval.

    Next: ApprovalPending for a new feature or work outside delegation, otherwise Ready.

  4. 04ApprovalPendingZ3 · Control plane

    New features, wider permissions and policy changes wait in the Owner's approval inbox. Approvals are signed, single-use and expire.

    Next: Ready if approved; Blocked if rejected or expired.

  5. 05ReadyZ3 · Control plane

    Approved by the Owner, or inside the scope the Owner has delegated.

    Next: Claimed.

  6. 06ClaimedZ2 · Agent factory

    One worker takes an atomic lease and reserves budget. Duplicate or reordered webhooks cannot start a second run.

    Next: Developing.

  7. 07DevelopingZ2 · Agent factory

    A coding agent writes the fix in its own sandboxed workspace, with filesystem, network and time limits.

    Next: QAEvaluation, with a patch, tests and artifacts.

  8. 08QAEvaluationZ2 · Agent factory

    A different agent grades the change against a read-only baseline: rubric score ≥ 85/100* and every hard gate. One failed gate vetoes any score.

    Next: Developing if it fails and a retry is allowed; ReleaseCandidate if score and gates pass.

  9. 09ReleaseCandidateZ3 · Supervisor

    An immutable candidate and its signed qa_receipt go to the trusted supervisor, the only unit that holds release rights. Rollback preflight runs first.

    Next: Canary.

  10. 10CanaryZ1 · Application

    Traffic moves 5% → 25% → 100%* while the error rate is compared with the baseline. Platforms without traffic splitting use blue-green with smoke tests.

    Next: Monitoring if healthy; RolledBack if the error threshold is exceeded.

  11. 11MonitoringZ1 · Application

    The factory measures the revision that is actually running, not the one it meant to ship. Low traffic switches to synthetic checks and a hold.

    Next: Verified after the post-deploy DoD and observation; RolledBack on regression.

  12. 12VerifiedZ1 · Application

    The observed revision meets the Definition of Done through the monitoring window.

    Next: Closed.

  13. 13ClosedGitHub

    Only now is the issue closed, with the changelog and feature catalogue updated. A merged pull request alone is not completion.

    End of the line.

  14. 14RolledBackZ3 · Supervisor

    The supervisor restores the last known good release on its own. Code and config are replaced; customer data is not overwritten.

    Next: Blocked, with evidence and a recovery report.

  15. 15BlockedZ3 · Control plane

    The issue stays open with evidence and a recovery report. Nothing is marked as a success.

    Next: Ready, only through a safe, authorized retry.

02 · What SISF is

One deployment. Three zones. One line.

SISF is an open-source framework for a closed-loop software factory. It takes in requests, writes and independently verifies code, publishes, monitors, rolls back and improves itself, all inside one deployment you own.

  1. N1

    One deployment, not three products.

    Application, agent factory and control plane share one factory_id, one release manifest and one lifecycle. They may run as several processes or containers; they are never split into separate services.

  2. N2

    GitHub is the source of truth.

    Source, policy, decisions and work items live in GitHub. Locks, jobs, the ledger and sessions live in the factory's own database, always pointing back to a commit or an issue.

  3. N3

    Two ways in.

    A labelled GitHub issue, or telemetry and feedback that the Decision Layer turns into an evidence-based proposal. Both loops close on a verified release.

  4. N4

    Yours, not a service.

    You run it on your own infrastructure with your own GitHub repository. Improvements stay in your deployment unless you choose to share them upstream.

Not in the first release

  • A multi-tenant SaaS, a marketplace or license sales.
  • A replacement for GitHub Actions, or its own Git server, registry or identity provider.
  • Opening new features on its own, or letting an outsider's issue widen permissions.
  • Claiming support for a platform before it passes end-to-end tests.

Free and open source.

Apache-2.0 · Copyright AgentKit.best

Use it, change it, run it for your own product. The license applies to the code and documents in the repository.

Read the license

03 · Architecture

Drawn to be trusted, not just to work.

Five details from the design. Every number marked * is a starting value, to be calibrated on real traffic before anyone relies on it.

Detail A

Three zones, one deployment.

Zones may run as several processes or containers. They share one factory_id, one release manifest, one gateway and one authority plane. Nine runtime units keep the same names on every platform; only their realization changes.

GitHub source of truth, outside the factory

Factory boundary · one deployment · factory_id

Z1

Application

The app your users use: Webapp, API, MCP and WebMCP. It emits traces, logs, sessions and feedback, and keeps serving the verified revision while Zones 2 and 3 restart.

  • appLong-running. Stable and canary revisions; scales horizontally.

Z2

Agent factory

Claims work and runs coding agents (Claude CLI, Codex and Pi built in; remote executors optional) and an independent QA agent.

  • dispatcherLong-running. One instance holds the lease; creates and destroys runners.
  • runnerEphemeral, one per run. No inbound connections, egress by policy, only that run's secrets.
  • qa-runnerEphemeral. Identity and credentials separate from the runner.

Z3

Control plane

Dashboard, API, CLI, MCP and WebMCP; GitHub and Google sign-in with roles; approvals, policies, budget and secrets; the trusted release supervisor.

  • controlLong-running. Not public by default, except the webhook route and the report endpoint.
  • supervisorA separate process. The only unit with deploy rights and the delegated signing keys.

Shared

  • stateSQLite WAL or PostgreSQL; one role per zone.
  • artifactsVolume or object store for artifacts, logs and snapshots.
  • edgeReverse proxy and TLS; splits stable and canary traffic.

Four network segments: app, factory, control, sandbox. Runners live in sandbox and reach the outside only through an egress proxy that enforces the Owner's allowlist.

Detail B

The QA gate: one score, eight vetoes, one signed receipt.

QA runs under its own identity, against a read-only test baseline locked to the commit and the policy SHA. It may use a judge model for semantic criteria; deterministic checks keep the veto.

Rubric · starting values*

  1. 30 Correctness and regression
  2. 25 Security and auth
  3. 20 Contract and data safety
  4. 15 UX, performance and output
  5. 10 Observability and rollback

* A design starting point, not a threshold proven by research. It is calibrated against real work.

Eight hard gates · any one fails, no release

  1. Tests and contract
  2. Permissions
  3. Migrations
  4. Secrets
  5. Confidence of the observed build
  6. Independent evaluator
  7. Resource and budget policy
  8. Rollback readiness

A high score never overrides a failed gate.

qa_receipt · signed by the trusted evaluator

candidate_digest
sha256:<digest>
suite_digest
sha256:<digest>
baseline_sha
<commit>
qa_agent
<identity>
model_route
coder <route> · qa <route>
checks
<8 hard gates>
score
<0–100>
timestamp · expires
<time> · <time>
evaluator_attempt
<n>

With two or more model routes, QA uses a different model or provider from the coding agent. With one, the receipt records same_model_route: true and policy may require the Owner instead. QA cannot grade an unfinished build or borrow another commit's receipt.

Detail C

Canary and rollback: measured, never assumed.

A release goes out in steps and comes back on its own. Every value here is a starting point*, to be calibrated on real traffic.

  1. Build immutable candidate
  2. Preview
  3. QA
  4. Rollback preflight
  5. Canary or blue-green
  6. Observed revision + metrics
  7. Promote or restore
Illustration of a canary release with automatic rollback Traffic to the new revision steps from 5 to 25 to 100 percent. A healthy error rate stays near the baseline, under the threshold. A faulty release crosses the threshold during the 25 percent step and the supervisor rolls back to the last known good release. Illustration only; values are starting points. 5%*25%*100%* err time → threshold 2%* baseline rollback → LKG
Illustration only. Solid: healthy release. Dashed: a faulty release crossing the threshold at the 25%* step, then restored to the last known good release.
Roll back when
The error rate exceeds the threshold after enough samples within a window, clearly above baseline. For example: 5xx > 2%* and more than 1 point over baseline*, at least 100 samples*, a 10-minute window*, two windows in a row*.
Stop at once when
A critical security or health check fails.
Hold when
Metrics are missing, there is no recovery version, or the deployment adapter is broken. Success is never assumed, and a successful deploy API call is not a healthy release.
Low-traffic hold
If real traffic cannot reach the sample count in the window, mandatory synthetic checks covering the DoD flows run throughout a hold of 30 minutes*. A real error during the hold extends it and is recorded; it does not trigger a rollback by itself. No synthetic suite, no self-publishing.
Never
Overwrite customer data with an old snapshot. Rollback replaces compatible code and config only.

Canary steps of 5% → 25% → 100%* apply where the platform can split traffic. Elsewhere the release starts with blue-green, smoke tests and monitoring.

Section A–A

The supervisor boundary.

The supervisor belongs to the same deployment (same factory.yaml, same factory_id, same install and uninstall lifecycle) but sits outside everything a candidate can change. All four conditions must hold.

Candidate side

  • Zone 1 and Zone 2 processes
  • Every agent workspace
  • The normal release pipeline

Supervisor side

  • Its own digest-pinned image
  • Last known good release (LKG)
  • Delegated signing keys
  • Rollback configuration
  1. Own image. The supervisor runs from its own digest-pinned image and is never built from the candidate's artifact.
  2. Out of reach. The LKG, signing keys and rollback configuration live on storage that Zone 1 and 2 processes and every agent workspace cannot write.
  3. Human-gated changes. The normal release pipeline cannot change the supervisor's digest; only a governance cycle with human approval can.
  4. Self-check. At startup the supervisor checks its own digest and refuses to run if it deviates from the signed manifest.

The P0 conformance checker verifies all four. If any one is missing, self-update is disabled, and a mode whose supervisor cannot be separated from the candidate must not self-publish.

Detail E · roadmap P3

Five surfaces, one service layer.

Every surface calls the same policy and action service. No surface defines permissions of its own, and a tool description never grants one.

  • DashboardOverview, workboard, run graph, telemetry and the approval inbox.
  • APIREST and OpenAPI: the contract every other surface uses.
  • CLIScripted operations, with device-flow verification for sensitive steps.
  • MCPRemote MCP with OAuth 2.1 and resource-bound scopes.
  • WebMCPOptional, in browsers that support it; falls back to API, MCP or the dashboard.

One action serviceSame permissions everywhere

Sensitive writes always go plan → approval → execute → audit, with step-up confirmation by a person. A browser agent cannot borrow the Owner's session to approve.

04 · Philosophy

Seven rules for software that agents write.

Every factory carries a written philosophy, signed by its Owner. Markdown guides the models; deterministic checks enforce the rules. Each rule below has a contract: how it is enforced, which acceptance test proves it, and where the brief defines it.

Status of every rule: designed, not yet built.

  1. I.

    New features belong to the Owner.

    Agents improve only what is already authorized.
    Enforcement
    ScopeDraft classifies every issue. A new feature, a wider permission or a policy change goes to ApprovalPending and waits for the Owner. A reporter, a label or an outside issue cannot widen scope or deployment permissions.
    Acceptance test
    SISF-03 An issue from a user without permission, or an unapproved feature, expands nothing; the feature lands in the approval inbox and needs an Owner decision.
    Brief
    §0 decision 12 · §5.3 · §5.4
    Status
    Designed, not yet built
  2. II.

    The agent that writes a change never grades it.

    Separate identity, workspace and, with two routes, model.
    Enforcement
    The coding agent and the QA agent run under different identities and workspaces. With two or more model routes, QA uses a different model or provider; with one, the receipt records same_model_route: true and policy may require the Owner. The QA baseline is read-only and pinned to the commit and policy SHA.
    Acceptance test
    SISF-06 A QA agent that scores its own patch is rejected; the receipt is pinned to the candidate SHA and an independent baseline.
    Brief
    §6.1
    Status
    Designed, not yet built
  3. III.

    A score never overrides a hard gate.

    Eight hard gates veto any score.
    Enforcement
    Tests and contract, permissions, migrations, secrets, confidence of the observed build, independent evaluator, resource and budget policy, rollback readiness. One failure blocks the release, whatever the rubric score (starting pass mark 85/100*).
    Acceptance test
    SISF-07 A QA score that passes while security or contract fails publishes nothing.
    Brief
    §6.1
    Status
    Designed, not yet built
  4. IV.

    No way back, no release.

    No safe rollback or no metrics means hold.
    Enforcement
    Rollback preflight runs before the canary. Missing metrics, no recovery version or a broken deployment adapter puts the release on hold; a successful deploy API call is never taken as a healthy release.
    Acceptance test
    SISF-20 A release without metrics or rollback capability is held or blocked; nothing self-publishes on an assumed success.
    Brief
    §3.3 · §6.2 · §10
    Status
    Designed, not yet built
  5. V.

    Done means observed.

    An issue closes only when the deployed revision meets its DoD.
    Enforcement
    The factory reads the revision that is actually running, measures it against the versioned Definition of Done through the monitoring window, and only then closes the issue and updates the changelog and feature catalogue. A merged pull request is not completion.
    Acceptance tests
    SISF-02 A labelled issue goes from intake to close with every milestone visible on GitHub and in the UI. SISF-08 Zone 1 goes up at the correct digest and the observed revision is checked.
    Brief
    §5.2 · §6.2
    Status
    Designed, not yet built
  6. VI.

    The factory may improve itself, never its own judge.

    Supervisor, keys, QA baseline and rollback rules change only through a human-approved governance cycle.
    Enforcement
    The factory can fix code in all three zones. A candidate cannot, in the same cycle, change the trusted supervisor, signing keys, policy enforcement, QA baseline or rollback rules; those are governance changes with human approval in a separate cycle. An unapproved agent PR to DECISIONS.md leaves the old policy in force.
    Acceptance tests
    SISF-10 The factory fixes a non-sensitive part of Zone 3 by itself, inside the same deployment, without the candidate replacing the supervisor. SISF-11 An unapproved agent change to DECISIONS.md leaves the old policy baseline in effect.
    Brief
    §4.1 · §6.3
    Status
    Designed, not yet built
  7. VII.

    When evidence is thin, do nothing.

    The Decision Layer chooses ignore or collect_more_evidence.
    Enforcement
    A signal needs data quality, enough samples, a baseline and a time range before it can become a proposal. With too little data the Decision Layer returns ignore, observe or collect_more_evidence and creates no issue. Model judgments can only raise caution; deterministic checks keep the veto.
    Acceptance test
    SISF-17 Telemetry with no activity or no benefit does not create issues indefinitely; the answer is ignore, observe or stop.
    Brief
    §4.2
    Status
    Designed, not yet built

Foundation files

The written philosophy of a factory lives in its own repository. Who may edit each file is part of the contract.

FileHoldsWho may edit
AGENTS.mdProduct context, ways of working, technical principles for agents.Agents may propose a PR; it carries no authority to change policy.
REVIEW.mdQA and release criteria, required evidence, the review checklist.PR with Owner approval. Agents never lower thresholds.
DECISIONS.mdPhilosophy, goals, no-gos, and how the Decision Layer classifies and prioritizes.PR with Owner approval, pinned to a SHA and a schema version.
FEATURES.md / features.yamlFunctionality approved by a person; behaviour and limits.Every new feature needs Owner approval.
docs/adr/Architectural constraints and the reasons behind them.Kept with history; the Owner reviews any change of decision.
.sisf/factory.yamlThe three zones, adapters, desired configuration and release policy.The Owner, behind branch protection.

Order of precedence: safety invariants in code and verified delegated authority, then Owner-approved policy at a protected SHA, then DECISIONS.md, REVIEW.md, FEATURES.md and ADRs, then AGENTS.md, then issues, comments and logs. A conflict means hold.

05 · Roadmap

Revision table.

What is being built, and what is still a drawing. The Go implementation of P0–P3 is in progress, Standalone and Docker modes first. Nothing is released yet.

Roadmap phases P0 to P4 with outcome, completion test and status
RevOutcomeDone whenStatus
P0ADRs, three-zone conformance checker, interface contracts.A configuration missing a zone, or a supervisor outside the boundary, is rejected.In progress
P1Local and Compose three-zone deployment, GitHub issue lifecycle, durable state.A fresh clone installs with one entrypoint; a labelled issue reaches Claimed; duplicate webhooks never start two runs.In progress
P2Two built-in agents, independent QA, publish with automatic rollback, factory self-update.Agent A patches, agent B grades, and an injected fault rolls back automatically.In progress
P3GitHub and Google sign-in, five control surfaces, Decision Layer, budgets.Permissions and behaviour are the same on all five surfaces.In progress
P4Remote agent adapters, Kubernetes and serverless profiles, a public conformance matrix.Two independent full deployment environments pass, and GO, MODIFY or STOP is decided on data.Planned

Deployment modes

  • StandaloneFirst · in progress
  • DockerFirst · in progress
  • KubernetesPlanned
  • VercelPlanned
  • CloudflarePlanned
  • TOSEPlanned
  • RailwayPlanned

A platform is marked supported only after it passes end-to-end tests for one deployment, durable tasks, safe execution and rollback. Open points still awaiting an Owner decision are listed in section 15 of the decision brief.

06 · Get started

Nothing to install yet. Three things to do today.

The repository holds the design. You can read it, follow the build, and tell us where it is wrong while it is still cheap to fix.

  1. 1

    Read the design

    The decision brief fixes the product decisions, interfaces, state machine, QA and release rules, and the acceptance matrix.

  2. 2

    Clone and follow the build

    Cloning gives you the documents today. Star and watch the repository to follow the Go implementation.

    git clone https://github.com/bestagentkits/sisf

  3. 3

    Review the design

    Weaknesses in the design are cheapest to fix now. Report security problems privately; open an issue for everything else.

Coming with the build

Not available yet
sisf doctor Not available yet
  • sisf doctor checks all three zones, GitHub permissions, the state store and rollback readiness before a real run.
  • A first-run wizard checks the GitHub App, sign-in and budget, then runs a sample issue through the whole lifecycle.
  • A local simulation mode with a fake GitHub and a fake agent runs the full lifecycle without spending tokens.

One-click deployment on TOSE, the creator's deployment platform, is in development and not available yet. SISF never requires it.

07 · Docs

Drawing index.

Everything that defines SISF today. The HTML pages are interactive: download them and open them in a browser.

  1. D-01Decision brief, EnglishFixed decisions, interfaces, the issue state machine, QA and release rules, phases P0–P4, acceptance matrix SISF-01 to SISF-20.
  2. D-02Decision brief, Vietnamese originalThe authoritative version if the two ever differ.
  3. D-03Architecture pageTopology, workflows, a playable state graph, trust boundary, deployment design per mode, roadmap. HTML source.
  4. D-04Architecture reviewA visual summary of the architecture. HTML source.
  5. D-05Security policyWhat is in scope and how to report a weakness privately.
  6. D-06LicenseApache-2.0.

End of drawing set

Free and open source. Apache-2.0.

Star the repository to follow the build, read the design, or tell us where it is wrong.

Star on GitHub Read the design

In development, not available yet. Dotted outline = not built yet.