Agent-Orchestrated Software

The definition

Three phrases carry the idea.

• “The user’s own AI agent.” The agent belongs to the person who runs the app. For Jane, that’s a parent’s bot. For a business, it’s the agent you already use.
• “Working from outside the app.” The agent reaches the app through doors the app builds for it. In Jane there are three: a read-only export, a file of rules, and a checker it has to pass before anything it writes goes live.
• “Doesn’t need to.” AI inside the app is optional. Jane chose to have none, and that choice gets its own section below.

The parts of an AOS app

Jane’s build breaks into eight parts, and they make a good template for any AOS app. Most are plain code or storage. One is a file of rules, one is a setup recipe, and one is the agent itself. The diagram shows the parts that run every day and night, and who touches what. The amber diamond is the checker, the one part that makes it safe to let an agent work while you sleep.

---
title: The parts of an AOS app as Jane builds them, and who touches what
---
flowchart TB
    classDef signal fill:#fef3c7,stroke:#f59d0e,stroke-width:1.5px,color:#0c0d10
    subgraph DAY["By day: the app runs on its own rules"]
        U["User"] <--> APP["App engine"]
    end
    STORE[("Store, in the owner's deployment")]
    subgraph NIGHT["By night: the owner's agent works from outside"]
        RULES["Rules file"] --> AGENT["Agent on a schedule"]
        AGENT -->|draft| VAL{"Validator"}:::signal
    end
    APP <--> STORE
    STORE -->|"export, read-only"| AGENT
    VAL -->|"pass: publish"| STORE
    AGENT -.->|"note, only when it matters"| OWNER["Owner"]
    OWNER -.->|"read-only report"| APP

Jane by day

Jane is a free learning app for kids in grades 3 to 6. A kid plays a short quest in a browser, about 8 minutes a day: a story, a few stops, and a boss battle with a medal to win. I designed it with my son, and Grok Bot wrote and revised the code from our feedback. It went from v0.1.0 on a Saturday to v0.5.0 the next Tuesday.

During the day there is no AI anywhere in the loop. The engine works from the open Marble Skill Taxonomy (v1), a map of 1,590 topics across 8 subjects joined by 3,221 “learn this first” links. With that map, the engine does five jobs:

• places the kid on the map and picks the next question
• credits the easier skills underneath when the kid gets a harder one right
• brings each skill the kid showed directly back for review at 1, 3, 7, 21, and 60 days, and the skills it only inferred later on
• grades every answer, and runs the “I’m stuck” button: a hint, then a worked example, then a free skip
• hands out medals only for answers right on the first try

Every rule is written in the code, so the same answers always lead to the same behavior. Progress goes to a store inside the family’s own setup: Cloudflare’s key-value storage (Workers KV) or a folder of plain data files on their own computer.

Jane by night

Around 1 AM, a scheduled routine on the agent’s computer runs six steps. In my house the agent is Grok Bot.

1. Back up. backup-progress.mjs saves the kid’s progress and prints its fingerprint (a sha256 hash, a short code that changes if even one character of the record changes).
2. Export. export-progress.mjs reads the day without changing it. It lists the answers, the weak spots, the topics ready next, and the reviews due. It also shows how much of each subject the kid has seen, and whether a quest is in progress.
3. Write. The agent writes tomorrow’s quest by the rules in LESSONS.md. If a quest is in progress, it rewrites only the stages the kid hasn’t reached yet.
4. Validate. publish-lessons.mjs checks the draft against the rules. A draft that fails writes nothing.
5. Publish. The quest lands in the store under lessons:DATE, waiting for the morning.
6. Verify. A second backup. Its fingerprint should match the first, which shows the kid’s record didn’t change during the run.

---
title: One night in Jane, and where the checker stands
---
sequenceDiagram
    participant A as Agent
    participant S as Store
    participant V as Validator
    participant P as Parent
    A->>S: 1. Back up, fingerprint A
    S->>A: 2. Export the day, read-only
    Note over A: 3. Write the quest by LESSONS.md
    rect rgb(254, 243, 199)
    A->>V: 4. Draft quest pack
    alt Breaks a rule
        V-->>A: Refused, nothing written
    else Passes
        V->>S: 5. Publish to lessons:DATE
    end
    end
    A->>S: 6. Back up again, fingerprint B
    Note over A,S: A must equal B
    A-->>P: Short note, only when it matters

Then the agent goes quiet. It messages the parent only when something matters: a failure, reviews falling behind, a struggle that keeps coming back, or a milestone. On a normal night, the parent usually hears nothing.

What the validator refuses

The validator is what lets the agent work unattended. It turns the teaching rules into checks a script can run. The cases the agent has to handle differently each get their own exit code (the number a script reports when it stops), so it knows what went wrong.

It’s the same review a careful editor runs (check the format, the size, and the gaps, then make the go or reject call), written as code and run every night. Tone gets a warning only, which leaves that call to people.

The validator also settles who does what. fOS sorts AI work into four roles: the AI leads, executes, assists, or stays out. Writing tomorrow’s quest is a lead task. The agent does the work, and people see only the exceptions. Grading answers during play sits at the other end. The AI stays out entirely, and plain code takes the seat. In fOS terms, a lead task is only safe when something checks every output before anyone sees it. In Jane, that something is the validator.

The design rule Jane adds

My definition leaves AI inside the app up to the builder. Jane keeps it out. Its setup guide tells the agent to “never add runtime AI,” and its architecture doc gives the reason in one line: “The AI is an author, not a chatbot.” It writes ahead of time, and the app shows only what was written and checked before the kid saw it. The docs list five payoffs.

The rule has a price. The deep rewrite happens once a night, so during the day the app adapts only as far as its written rules reach. And the agent does read the day’s export, so the docs give parents a plain warning: pick an agent you trust with it.

The contract between Jane and its agent

The whole interface between Jane and its agent is two scripts and one file of rules: export-progress.mjs, publish-lessons.mjs, and LESSONS.md. That narrow seam is why the rest works.

Because the seam is small, the agent can be anyone. Grok Bot runs it in my house. Any agent that can run small programs on a schedule can run it somewhere else. A parent can do it by hand: export, write a quest file, validate, publish. Even a plain scheduler (cron, the clock-based job runner built into Mac and Linux) can start the export at 1 AM:

0 1 * * *  cd /path/to/jane && node export-progress.mjs >> exports/nightly.log 2>&1

The seam also lets the app and the agent improve on separate tracks. The code’s authors still ship updates. The agent gets better whenever its model does. Neither one waits for the other. The docs name one planned addition: a rules-based quest writer built into the app, so the nightly cycle would work with no agent at all. A quest written by an agent or a person would still take priority. It isn’t built yet.

Deploy and share

The same code runs three ways, on the agent’s own computer or anywhere the family chooses.

Sharing works the same way. Another family imports the Jane bot template. Their bot reads BOT-SETUP.md, asks the parent its setup questions one at a time, and installs a copy of its own. Each family’s data stays in its own setup. None of it is ever committed to the shared code, because the repo is set to ignore those files.

Jane’s docs compare AOS with the two usual ways software reaches people.

AOS in a business

Jane’s design leans on three things: a map of what has to come first, rules that fit in code, and a quiet window each night for the thoughtful work. Many business owners already have all three, even when the map lives in their own head. Two sketches of what that could look like:

A new-hire onboarding app. By day, a new hire works through short daily tasks in a browser. The app checks answers against your written procedures and brings key steps back for review. By night, your agent reads the day’s export and writes tomorrow’s tasks, following your map of what a new hire must learn first. The validator refuses any task that skips a step on the map or names a policy your handbook doesn’t contain. You get a read-only report, and a note only when someone is stuck.

A client portal for a service business. By day, each client sees their plan, their checklist, and what’s next. Plain rules mark tasks done and flag what’s late. By night, your agent reads the day’s activity and drafts each client’s next steps. The validator refuses any message that promises a date or a price outside the rules you wrote. Client data stays in your own account.

In both, the map is the hard part. Marble gave Jane a free one. A business has to write its own: the order in which a new hire, a client, or a customer has to learn things. That map is what your agent builds on every night.

When AOS fits

Four questions decide it.

On cost, the comparison is your hosting (often a free tier) plus the agent you already pay for, against a subscription per seat. The data stays in your deployment, apart from the exports and backups your agent keeps on its own computer, and the code is open (MIT), so there’s little to be locked into. Setup is the cost to plan for. Someone points an agent at the recipe once and answers its setup questions. Jane’s recipe is one guide written for the agent to read, and it points the agent to the install and lesson-rules files. Jane itself went from first release to v0.5.0 between a Saturday and the following Tuesday, with an AI agent writing the code.

A build checklist

Ten rules, taken from how Jane is built.

1. Write the app’s rules into its code. Same input, same behavior.
2. Give the agent a read-only export of the day.
3. Put the authoring rules in one file the agent reads every night.
4. Put a validator between the agent and the store. A failed draft writes nothing.
5. Give each refusal the agent must handle differently its own exit code, so it knows what to fix.
6. Lock anything the user has already seen.
7. Fingerprint the user’s record before and after the agent runs.
8. Keep the app working when the agent skips a night.
9. Ship the setup recipe with the code, and keep each user’s data out of the repo.
10. Have the agent speak up only when something matters.

Next step

Sources and credits

• Jane guide site: https://kentlangley.github.io/Jane/ (guide CC BY-SA 4.0)
• Jane code: https://github.com/kentlangley/Jane (MIT)
• The technical version, in the repo: docs/ARCHITECTURE.md and docs/NIGHTLY.md
• The definition and the comparison table are adapted from Jane’s docs (CC BY-SA 4.0, Kent Langley).
• Marble Skill Taxonomy (v1) · © Generative Spark, Inc. (Marble) · https://withmarble.com · licensed under ODbL 1.0 (database) and CC BY-SA 4.0 (content).