tensquads — What we build

2026-11-11 · Moe Ghashim

Read this page from the top. Each part uses the ideas of the parts before it.

Contents

1. How tensquads works. What the product is, with one picture and one example.

2. Words we use. The meaning of each important word.

3. The bots and the persons. The five bots of the MVP, and the role of each person.

4. How Petra works. How Petra makes decisions and reads the business.

   • How Petra decides

   • Performance review and suggestions by Petra

   • Fast decision model (Jev)

5. How the owner speaks to Petra. The chat, email and WhatsApp.

   • Cards in the chat with Petra

   • Email and WhatsApp for Petra

6. How a bot does a task. The bot, the image, the sandbox and the state.

   • In simple words: bot, image, sandbox and state

   • Inside a bot

   • How a result is checked

7. Credits and prices. The packages, the price of each task, and the cost.

   • The pricing structure

   • Price, cost and the super admin dashboard

8. What the squad remembers and learns. The memory, the trails and the learning.

   • Memory

   • Trails

   • Learning

9. How we build it. The rules for the code and the tools.

   • Architecture

   • Where each part runs

   • Where the state is

   • Technologies and tools

   • Clear expectation and a video for every feature

   • The loop in detail

10. Feature list. All the features of the MVP, with the priority and the person who added each one.

    • Roadmap and future squads

11. Decisions. The questions that have an answer.

12. Test cases. The success cases for each bot.

13. Research and sources. What each reference says.

14. Open questions. The questions that have no answer.

1. How tensquads works #

tensquads gives a small business a squad of bots. The bots do the work for the business. The owner speaks to one bot only. Its name is Petra. Petra gives the tasks to the other bots, and the owner sees the result.

A company can launch with us: research the competition, build the website, and add support when there is a need for it.

Each bot completes its task and gives the result to Petra. Only Petra sends messages to the owner.

One request, in sequence

1. The owner makes a request. Example: "Build my website."

2. Petra selects the bot. In this example, Petra selects Angkor. For an automatic event, such as a new Google review, a fixed rule selects the bot.

3. The system does a check of the credit balance. If the balance is not sufficient, the system tells the owner to pay or to upgrade.

4. The bot does the task on Cloudflare. It uses an isolated sandbox only for a tool that needs a real computer. The bot cannot send a message to the owner. The bot cannot give the task to a different bot.

5. An action with a risk does not start without approval. If an action publishes, pays or refunds above the limits of the owner, the owner must approve it first.

6. Petra gives a report. Petra shows the result, for example a preview link. Petra also tells the owner which work remains.

7. The squad keeps a record. The system records each step. The squad keeps the knowledge for the next task.

2. Words we use #

Read these words first. All the parts below use them.

3. The bots and the persons #

Each bot is a character. The name of each character comes from a famous place. Refer to 10squads.com/design/#mascots.

From left to right: Petra, Machu, Angkor, Kyoto and Greenwich.

The MVP has these five bots. The roadmap bots (Analytics, Accounting, Finance) and the future squads come after the MVP. The success cases of each bot are in Part 12.

Roles #

Each bot has one role. The role tells you what the bot does, what it does not do, and to whom it speaks. The roles of the bots are in the table of the bots above. The persons also have roles:

4. How Petra works #

Petra receives each request and each event. This part shows how she decides what to do, how she reads the performance of the business, and how a fast model helps her.

How Petra decides #

Petra makes a decision for each request and each event. She does it in a fixed sequence of questions. Three parts of the system give the answers, and the owner gives the answer when the three parts cannot.

Routing sends each task to the correct bot. A message from the owner always goes to Petra, and Petra selects the bot. An automatic event, such as a new Google review, obeys a fixed rule if one applies. If no fixed rule applies, the event goes to Petra. The system does not give a task to a different bot without a report. If the bot is not available, the system tries again. If the task still fails, Petra tells the owner.

The sequence of questions

If all the answers are yes, the bot does the task, and Petra gives the report.

The rules for each decision

1. Petra records each decision in the trail, with its reason.

2. When the owner asks "Why?", Petra gives the reason in simple words. The reason agrees with the trail.

3. Petra cannot increase her own limits. If the owner asks for more freedom for Petra, that is a change to a rule, and the owner must confirm it.

4. When a number or a rule can give the answer, the code decides, not the model.

Rules and approvals. The owner sets the limits. Example: "Refund without my approval below $20." In the limits, the bot does the action. Out of the limits, Petra asks the owner, and the action does not start until the owner approves it. The system cannot increase its own limits. It can only recommend a change.

For the builders. These rules make the routing safe:

1. A message from the owner always goes to Petra. For each other event, a table of fixed rules in the database gives the bot. The most specific rule applies.

2. If no fixed rule applies, Petra selects the bot from a list of what each bot can do. The system records the selection and its reason.

3. The system does not change the bot silently. If no bot is correct, or the bot is not available, the task waits and the system tries again. Then the task goes back to Petra, and Petra asks the owner.

4. A bot does not give its task to a different bot, and it does not send a message to the owner.

5. Two bots can send messages to each other only if a list permits that pair.

6. Each account is isolated. Each query has the id of the account. Each bot has its own memory area and its own list of permitted tools.

The loop of Petra

Petra is always on, and she does not work in a sandbox. She uses the same loop design. For Petra, each bot is a tool: she starts a bot and gets only its last result, not all its turns. Thus the context of Petra stays small. For each message or event, she does this sequence:

1. She reads the state of the account from the database.

2. She makes the decision, with the sequence of questions in Part 4.

3. She answers the owner, starts a bot, or asks the owner for an approval.

4. She writes the state to the database, and she waits for the next message or event.

Performance review and suggestions by Petra #

Petra reads the performance of the business at regular intervals. She then suggests changes that can improve it. A change can be to the website, to the Google Maps listing, to the support answers, or to a different area of the business. Petra does not make a change without the approval of the owner.

Signals, not single events. Petra does not react to each piece of information. One complaint is an event. A bot answers it, and Petra records it. Petra makes a suggestion to the owner only when the event becomes a signal. An event becomes a signal in one of two ways:

1. A measurement confirms it. If a problem can be measured, Petra starts an audit. She makes a suggestion only if the audit finds the problem.

2. It occurs again. If a problem cannot be measured, Petra counts the events of the same type. Three events or more in one week are a signal.

The picture shows the two ways.

Jev helps here also. For each new complaint, the code asks Jev: "Is this complaint about the same problem as these earlier complaints?"

How Angkor does the audit of the website. This is a proposal.

1. Petra gives Angkor the task "audit the website".

2. The loop of Angkor asks for a browser. The system starts a sandbox, and the sandbox opens the website in a real browser, as a customer does.

3. Angkor measures the website five times: on a computer and on a phone. It records the time to load, the size of the page, and each error.

4. Angkor compares the numbers with the limits. Example of a limit: the page loads in less than 3 seconds.

5. Angkor gives Petra a report: the numbers, the cause of the problem if it found one, and the change that it recommends.

6. If all the numbers are in the limits, the report says "no problem found", and Petra makes no suggestion.

Where the data comes from

Sales and orders are not in the MVP, because no bot reads them. The roadmap bots (Analytics, Accounting, Finance) can add them later.

The sequence

1. Each week, Petra collects the data from the four sources.

2. Petra finds what changed. Example: "Calls from Google Maps decreased by 30%."

3. The large model writes possible suggestions. Example: "Add the lunch menu to the Google Maps listing."

4. Jev gives an answer to small questions about each suggestion.

5. The code uses the answers of Jev to remove the weak suggestions and to put the others in sequence.

6. Petra shows the owner a maximum of three suggestions. Each one shows the evidence and the price in credits.

7. The owner approves or rejects each suggestion. An approved suggestion becomes a task for a bot.

8. After some weeks, Petra measures the result and records it in the memory.

How we use Jev here

Jev does not write suggestions. It answers many small questions quickly and at a low cost. This feature has many such questions, so it is a good use of Jev.

The rules

• Each suggestion shows its evidence, with a number.

• Petra shows three suggestions or fewer for each week. The owner has little time.

• If the owner rejects a suggestion, Petra does not make the same suggestion again.

• If a suggestion did not improve the result, Petra records that, and she gives less weight to similar suggestions.

Fast decision model (Jev) #

Jev is a small, fast model with a low cost. It answers only two types of question: "yes or no?" and "which one?". The bots make many such decisions each day. We use Jev. We can test Sage, a model from a different company, later. The plan has three steps:

1. Build with the large model.

2. Record each decision.

3. Test Jev with those records, and change one use at a time.

The problem that Jev solves. Each task has small decisions. Which bot gets this task? Is this refund in the rules of the owner? Is this reply safe to send? Without Jev, the large model answers each of these questions. That takes seconds and costs more for each call.

An example. Sara has a grocery shop and uses tensquads. She has this rule: "Refund without my approval below $20, if the item was damaged or missing."

A customer writes to the shop: "My eggs arrived broken. I want my $15 back."

Kyoto must find if this message obeys the rule of Sara. This needs three small decisions. Jev reads the message and answers three questions:

Jev does not know the limit of Sara, and Jev does not make the decision. Our code makes the decision from the rule of Sara and the answers of Jev:

• Jev is sure about all three answers, and $15 is below $20. Kyoto refunds the $15 and tells the customer. Petra does not interrupt Sara.

• Jev is not fully sure. Example: 70% that the reason is "damaged". The refund waits. Petra asks Sara: "A customer wants $15 back for broken eggs. Do you approve?"

• Jev is not sure. Example: the message is "this order was bad". Kyoto does nothing with money. Petra sends the message to Sara.

If the customer asks for $60, the answer is always "ask Sara", because $60 is above her limit. Our code does this check with a simple calculation.

Why we divide the work this way. A model is good at reading a message and finding its meaning. Code applies a money limit exactly, and we can test it. Thus the model reads, and the code applies the rule. The percentages in this example are not real. Moe sets the level at which Jev is "sure".

Where we use Jev

5. How the owner speaks to Petra #

The owner speaks to Petra in three places: the chat in the app, email and WhatsApp. This part shows what the owner sees in each place.

Cards in the chat with Petra #

This is an important use case. The owner speaks to Petra in the chat, and Petra shows cards in the chat. A card is a small part of a screen in a message. The owner reads the card or selects a button on it, and does not go to a different screen.

This picture shows how the chat looks. The names and the numbers are examples.

The chat with Petra uses OpenUI. This is a decision, and it is a part of the MVP. We make our own components with the tensquads design.

The rules for the cards:

1. Each card also has a text form. Email and WhatsApp show the text form, because they cannot show a card.

2. Our code makes each approval. The model can only show an approval that the system made. A click goes to our code.

3. After the owner selects a button, the card shows the selection, and the buttons go away.

4. Petra can show only the cards in this table.

Email and WhatsApp for Petra #

When an owner signs up, the system gives Petra two addresses for that business. Only the owner writes to these addresses. The customers of the business do not use them.

1. An email address. The service is AgentMail. The system makes one inbox for each owner. The Petra of that owner is responsible for the inbox.

2. A phone number for WhatsApp. The service is AgentPhone. A number costs $3 for each month. Only a business in the United States or Canada gets a number. Each business has its own WhatsApp Business account.

A message that comes to one of these addresses is an event. It goes to Petra, the same as a message in the chat. The routing rules in the section above apply.

6. How a bot does a task #

Petra gives each task to one bot. This part shows how the bot starts, does the task and gives the result to Petra.

In simple words: bot, image, sandbox and state #

Read this section first. A bot does not run in a sandbox. A bot thinks in one place and works with its hands in a different place.

• Cloudflare is where the thinking is done. Petra is there, and the loop of each bot is there. The loop is the code that asks the model "what is the next step?" and reads the answer.

• boat.dev is where the work with the hands is done. A bot uses it only when it must operate a real computer: open a website in a browser, read the pages of a competitor, build a web page, or run code.

The image is the template, and the sandbox is one computer made from the template. The system deletes the sandbox after the task. Nothing is lost, because the state was never in the sandbox.

When a sandbox starts

A sandbox starts only when the model asks for a tool that needs a real computer. A sandbox does not start for thinking, for writing an answer, or for reading the memory.

Example 1: no sandbox

A customer asks Kyoto: "Are you open on Sunday?"

1. The loop of Kyoto, on Cloudflare, reads the opening hours from the database.

2. The model writes the answer.

3. The answer goes to the check, and then to the customer.

boat.dev is not used. Thus the answer is quick.

Example 2: with a sandbox

The owner asks Petra: "Who are my competitors?"

1. Petra, on Cloudflare, gives the task to the loop of Machu, also on Cloudflare.

2. The model says: "I must read these five websites."

3. A browser is necessary to read a website. The system starts a sandbox on boat.dev from the image of Machu.

4. The sandbox reads the pages and gives the text to the loop. The same sandbox does all the reading for this task.

5. The model writes the result. The result goes to the check, and then to Petra.

6. The sandbox stops, and the system deletes it.

The system writes each step to the database. If the sandbox breaks at step 4, the system starts a new sandbox, and the task continues.

A sandbox cannot see the data of a different account or of a different task. A sandbox keeps no data after it stops, and it has no keys. If a sandbox breaks, the loop gets a failed tool result, and the system starts a new sandbox. The session, the memory and the trails are in the database, not in the sandbox.

Only Petra is always on. The loop of each other bot runs only while it has a task. A simple task, such as one answer by Kyoto, needs no sandbox, so it is quick. The repository has a boat.dev adapter now.

Inside a bot #

This section is a proposal. The design of the loop follows the agent loop of the Claude Agent SDK. The section shows what a bot contains and how its loop runs. The detail for the builders is in Part 9, "The loop in detail".

What a bot contains

The model is not in the image. The bot calls the large model through a port. Each model is a plug-in behind this port, so we can replace the model and change no bot. For this reason, we write our own loop with the design of the reference, and we do not use the Agent SDK as the engine, because it runs only Claude models.

What the loop gets when a task starts

• The task from Petra, with the necessary result.

• The core of the memory of that business.

• The rules and the limits of the owner.

• The id of the account and the id of the task.

The loop

1. Receive. The loop gets the task from Petra, the instructions of the bot, the definitions of its tools, the core of the memory and the rules.

2. Evaluate. The model reads all of this and answers. The answer has text, one or more tool requests, or both.

3. Execute. Our code does a check of each tool request against the rules, and then it runs the tool. A tool that needs a browser or code runs in the sandbox. Tools that only read can run at the same time. Tools that change something run one after the other. The results go back to the model.

4. Repeat. Steps 2 and 3 are one turn. The turns continue until the model answers with no tool request.

5. Result. The last answer is the result. A checker that is not the maker tests the result. Then the bot gives the result and the evidence to Petra.

A simple task, such as one answer by Kyoto, needs two or three turns. A research task by Machu can need many turns.

How the loop stops

The loop stops in one of these ways. Each way has a name, and Petra reads the name to know what to do.

Each result has the cost, the number of turns and the id of the session, also when the task fails. The super admin dashboard uses these numbers.

What a bot cannot do

• It cannot send a message to the owner. Only Petra does this.

• It cannot give its task to a different bot.

• It cannot do an action above a limit of the owner. It asks Petra, and Petra asks the owner.

• It cannot see the data of a different account or of a different task.

How a result is checked #

A loop that runs alone also makes mistakes alone. Thus "done" must be a result that is tested, not a statement by the bot. The rule: the model that did the task never decides that the task is complete. In this section, the maker is the bot that did the task, and the checker is the part that tests the result.

The five layers

1. A written check for each type of task. The definition of the bot has a list of conditions that can be tested. Example for Machu: five competitors, each with a source that opens.

2. Evidence with each result. The maker gives evidence for each condition: a link, a screenshot or a measured number.

3. Tests by code. Our code tests what it can with no model: the links open, the page loads, the price is in the limits, and the text does not break a rule in the core of the memory.

4. The checker. A different model tests each condition that code cannot test.

5. The owner and the team. An action with money, or an action that the public sees, needs the approval of the owner. Each week, the team examines a sample of the tasks. A result that the owner rejects or changes becomes a test case.

The checker

How we know that the checker is good

• Each answer of the checker goes in the trail.

• We compare the answers of the checker with what the owner did later. If the owner rejects a result that the checker accepted, the checker made a mistake.

• The checker has its own test cases: wrong results that it must find.

The numbers in this section are a start: one more try, and a sample each week.

7. Credits and prices #

Each account can use all the bots. Before a task starts, the system does a check of the credit balance of the account. If the balance is not sufficient, the task does not start. The system then tells the owner to pay or to upgrade. There are three subscription packages, as in the design: Starter $49, Growth $149 and Scale $399 for each month. Each package includes a number of credits. The owner can also buy credit packs. The credits come in increments of 1,000. Starter includes 1,000 credits, Growth 3,000 and Scale 8,000. A credit pack is 1,000 credits for $50.

The picture shows the check of the credits for one task.

The pricing structure #

This structure is a proposal. Moe decided five points: one credit is 5 cents, the credits in each package, the credit pack, the system takes the credits before a task starts, and a failed task costs nothing. The other numbers are a start. We change them by trial and error, with the data from the super admin dashboard.

1. The value of a credit

1,000 credits cost $50. One credit is 5 cents.

2. The subscription packages

3. The credit packs

An owner buys a pack when the credits of the month are not sufficient. Start with one pack size. Add larger packs only if owners ask for them.

4. The price of each type of task

These prices are a first estimate. We do not know the real costs at this time.

With these prices, a Starter owner can do one research task, one website, five changes and 50 customer answers in one month.

5. The rules

1. The system takes the credits before the task starts.

2. If the task fails, the system gives the credits back.

3. The system uses the credits of the subscription first, and then the credits of a pack.

4. The credits of the subscription stop at the end of the month. The credits of a pack stay for 12 months.

5. A chat with Petra costs no credits, so the owner can always ask a question. The weekly performance review by Petra and the audit of the website by Angkor are a part of each package and also cost no credits. Petra tells the owner the price of a task only when the credits are not sufficient for it.

6. The 14-day trial gives 600 credits. This is sufficient for one research task and one website.

6. How we adjust the prices

1. Each week, the team reads the super admin dashboard.

2. The target: the real cost of a task is 30% of its price or less.

3. If the real cost is above 40% of the price, increase the price.

4. If the real cost is below 15% of the price, the team can decrease the price.

5. A new price applies to new tasks only.

Price, cost and the super admin dashboard #

The owner pays a fixed price for each type of task. The price does not change if the task uses more work than usual. Two words are important here:

• Price is the number of credits that the owner pays.

• Cost is the money that the task costs us: model use, sandbox time and external services.

The team uses the dashboard to compare the price with the real cost. If the cost is too near the price, the team changes the price list.

1. The system reads the price from the price list.

2. The system does a check of the credit balance.

3. The cost estimator calculates the cost that we expect for the task.

4. Petra gives the task to the loop of the bot.

5. The loop runs until the task is complete. It uses a sandbox only for a tool that needs a real computer.

6. The result goes to the check, and then to Petra. If a sandbox started, it stops.

7. The system records the price and the real cost.

8. The super admin dashboard shows the price and the real cost for each type of task.

9. The team changes a price when it is necessary. The new price applies to new tasks only.

What the dashboard shows

The repository has a super admin area now, with a Companies screen and a Squad images screen. This dashboard is a new screen. It needs a design before we build it.

8. What the squad remembers and learns #

The squad keeps what it learns about the business. This part shows the memory, the trails and how the system uses them to improve.

Memory #

The squad remembers the business, so the owner does not have to give the same information again. The memory has four layers:

1. The full record of all messages.

2. The notes that each bot writes after a task.

3. One page for each subject, such as the menu, the suppliers and the competitors.

4. A small core that each task reads.

The picture shows the four layers. The core is small, and the record is large.

Each night, a job corrects and combines the notes. A sandbox keeps no memory.

For the builders. The four layers in the database:

• Each row has its origin (owner, bot, not trusted, system), its source and its date. The system sets them. Only the rows from the owner and from a bot can go into the core.

• A preference of the owner is an instruction. A new preference replaces the old one. The facts are separate.

• The search uses words and meaning together. It gives more weight to new and important rows. It stays in one account.

• Before the system makes a long chat shorter, the bot saves the important points as notes.

• Each night, a job for each account compares the notes with the record of messages and combines them. It keeps the earlier version and a list of the changes.

• A sandbox keeps only a temporary copy for reading.

The Memory screen (design proposal). The owner uses this screen to read and correct the memory of the squad. It is a new item in the menu, below Rules.

The screen has three areas:

1. Petra always remembers. This is the small core that each bot reads before each task. The owner can add, edit or forget an item. The maximum is 20 items.

2. Pages. One page for each subject, such as Menu, Competitors and Customers. Each fact shows who found it and its sources. The owner can correct a fact or tell the squad to forget it.

3. Recent changes. A record of each change to the memory. The owner can undo a change for 30 days.

The rules of the screen:

• The word of the owner always wins. After the owner corrects a fact, the fact belongs to the owner, and no bot can change it.

• When Petra is not sure about an old fact, she asks the owner: "Still correct?"

• When the owner forgets a fact, it goes out of all the bots at the same time.

This is a proposal. The numbers 20 and 30 are a start. The text and the colours use the tensquads design tokens.

Trails #

A trail is the full record of one task. It contains each message, each use of a tool, each decision and each approval, in sequence. The team uses the trail to see what a bot did and why. The system keeps a trail for one month. Only the super admin of tensquads can see a trail. The owner cannot see it. The system keeps the approval records for more than one month, as evidence of each approval.

For the builders. What the trail contains, and what the plan has now:

How we store the trail

• One table. The system only adds rows. It does not change a row.

• One id for each task. It connects all the rows, from the message of the owner to the last result. One query gives the full trail.

• Large items go to object storage (Cloudflare R2): screenshots, copies of pages and long records. The row keeps a link and a hash.

• The screens read views that the system calculates from the table.

• A sandbox keeps nothing. When a sandbox stops, no trail is lost.

Learning #

The system uses the trails to improve in two ways. For one business, the squad learns the preferences of that owner, and Petra recommends changes to the rules. For the full product, a task that failed becomes a test case. First, the system removes the customer data. Then the tensquads team examines the test case. A change to a bot must pass these tests before release.

The signals that the trails give

Loop 1: for one business

1. After each task, a bot writes a note of what it learned.

2. Each night, a job compares the notes with the trail, combines them and updates the core of the memory.

3. A correction from the owner becomes a preference. A preference is stronger than a note of a bot.

4. Petra recommends changes to the rules from what she sees. Example: "You approved 12 refunds below $20. Do you want to increase the limit?" The owner decides. The system does not increase its own limits.

Loop 2: for the full product

1. Each task that failed, or that the owner asked to change, can become a test case. First, the system removes the customer data.

2. The image of each bot has a set of these test cases. A change to a skill or to a prompt must pass the set before release.

3. A change goes out in three steps: Draft, Beta, Stable. We compare the signals between the steps before we continue.

4. If a change makes a signal worse, we go back to the old version. The old plug-in is still there.

5. The failures that occur again and again go to the counts of bugs and requested features on the Squad images screen.

The safety rules

• The data of one account does not go to a different account. Only test cases with no customer data, and totals, go across.

• The owner can always read and correct what the squad learned.

• A test or a person approves each change. No bot changes its own skills.

9. How we build it #

This part is for the persons who build the system. It gives the rules for the code, the tools, and the rule for each feature.

Architecture #

Four rules tell us how to build the code. The repository obeys the first two rules in part. The notes tell you what is there now and what to add.

Domain-driven design. We divide the code into business areas, not into technical layers. Each area has its own words, data and rules. Each area is one plug-in. The areas use events to send information to each other. No area reads the tables of a different area. The screens, the code and the documents use the same word for the same thing.

Anti-corruption layer. Our code does not use the words of an external service. We define a port for each external service in our own words. An adapter behind the port changes our words into the words of the service. The names and the data shapes of the service stop at the adapter.

The picture shows four of the ports. The table below shows all of them.

The benefit: we can replace Jev with Sage, or replace one payment provider with a different one, and no business rule changes. A test makes sure of this. No file in a business area can import an adapter or an external library.

Keys. The keys of all the outside services are in a vault: the model, Google Maps, AgentMail, AgentPhone and payments. Our code calls each service through a proxy, and the proxy adds the key. The model and the sandbox do not see a key. Thus an attack on a bot cannot get a key.

Adversarial review. The decisions set the architecture. A pull request does not change it. For all other requirements, a reviewer tries to find a fault. The reviewer is not the builder. The reviewer must show evidence for each requirement. A report of "no fault found" without evidence is a fault.

The Reviewer role is in the repository now, for screens. This rule adds the requirements in the table above to that role.

Plug-in framework. Each part of the system is a plug-in, as in the DeepSeek projects. Thus we can replace a part without a restart. The base is there now. We must add four tests that prevent drift:

1. You can remove a plug-in, and it leaves nothing behind.

2. A plug-in does not import a different plug-in.

3. Each piece of state has one writer.

4. The documents agree with the code.

Where each part runs #

This section shows where each part of the system runs, and which parts are always on. The app and Petra are always on. A bot is not a server. The loop of a bot runs on Cloudflare while the bot has a task. A sandbox runs only the tools that need one.

Each outside service is behind a port, as the Architecture section shows. Petra does not run all the time. She starts when a message or an event comes, does her work, writes the state to the database, and then waits. The loop runs on Cloudflare and calls the large model through the model port. A sandbox does not call the model. The keys of all the outside services are in a vault, and each call goes through a proxy that adds the key.

Where the state is #

Keep the state out of Petra. Petra reads and writes the state, but the database keeps it. If Petra stops or gets an update, no data is lost. Petra starts again and reads the state from the database.

One writer for each account prevents two bots from changing the same data at the same time. The plan agrees with this recommendation: Petra runs on Cloudflare, and the database is Neon.

One database for all the businesses, or one store for each business. One database can hold 10,000 businesses; the quantity is not the problem. The risk is isolation: with one database, one error in the code can show the data of one business to a different business.

The decision: option A for the MVP, with a second safety layer in the database. The second layer makes the database refuse a row that is not for the business that asks. Then option D, when the number of businesses increases or when a customer asks for isolation. We do not use option C.

The loop in detail #

This section is for the builders. Part 6 shows the loop in simple words. This section gives the controls, the hooks, the context, the session, the plug-ins, and how we add a new bot.

The controls of the loop

When our code refuses a tool request, the model gets the refusal as the result. Then the model tries a different method, or it reports that it cannot continue.

The hooks

A hook is our code that runs at a fixed point of the loop. A hook does not use the context of the model.

The context

The context is all that the model can read in one turn: the instructions, the tool definitions, and the earlier turns with their tool results. It becomes larger with each turn. When it is almost full, the loop makes a summary of the old turns. A summary loses information, and we cannot get that information back from the summary. Thus the full record of the task stays in the session, outside the context. The loop can read an old part of the session again when the model needs it. The permanent rules are in the instructions of the bot, not in the task message.

Stop and continue

Each task is a session with an id. The session is the full record of the task: each message, each tool request and each result, in sequence. The system only adds to it. It is in the database, not in the sandbox and not in the loop. It is the same record as the trail. Because the loop keeps no state, a new loop can read the session and continue from the last event. When a bot needs an approval, the loop and the sandbox stop. After the owner approves, a new loop continues the session. This is a decision.

The loop as a plug-in

The loop is one plug-in, and each bot is one plug-in. No bot contains loop code.

The loop plug-in has the hook points. The other plug-ins add their hooks to these points. When we remove a plug-in, its hooks go away with it, and it leaves nothing behind.

When the model changes

A rule in the loop that helps a weak model can make a strong model slower. When we change the model plug-in, we examine the loop again. We run the test cases of each bot, and we remove each rule that does not help.

How we add a new bot

A new bot is one new plug-in. No other plug-in changes.

1. Make one folder for the bot, with its definition: instructions, skills, permitted tools, the check, the limits, and the price of each type of task.

2. If the bot needs a new outside service, add a port and an adapter for it.

3. Add the test cases of the bot.

4. Add the plug-in to the list of plug-ins. Then Petra finds the bot in the list of what each bot can do, the price list has its prices, and the system builds its image.

The roadmap bots and the future squads come in this way.

Technologies and tools #

This table shows each tool, its use, and its status. "In the repository" means that the code uses the tool now.

Clear expectation and a video for every feature #

We do not start a feature until its expectation is written. We do not accept a feature until a person sees it operate.

1. Write the expectation before the work starts. Use simple words. Write what the feature does, who uses it, and what the correct result is. Use the cases in Part 12 as the model: one line for the action of the owner, and one line for the necessary result.

2. The coding agent builds the feature. It builds only what the expectation says.

3. The coding agent records a video. The video shows the feature from start to end. It shows the written cases in sequence.

4. The coding agent attaches the video to the pull request. The person who examines the pull request sees the video and compares it with the expectation.

5. A difference is a fault. If the video does not show a written case, the pull request goes back. If the video shows something that the expectation does not include, the pull request also goes back.

The repository asks for screenshots and automated tests now. This rule adds a video. The test tool that runs the automated tests can also record the video. Thus the agent records the tests while they run.

10. Feature list #

This is the only list of the features that we build. Add one row for each feature that you want. Write your name in the "Added by" column. Set the priority. Parts 3, 4 and 5 give an explanation of each feature.

Roadmap and future squads #

These bots and squads are not in the MVP, and they are not in the feature list above. The roadmap bots come first. The future squads come after them. Moe will add more to the roadmap.

11. Decisions #

Each row is one decision that Moe made. The parts above use these decisions. To change a decision, add a question to Part 14.

12. Test cases #

These are the success cases for the MVP bots. Select Yes, Later or No in the last column. Each case uses a restaurant or a grocery shop, the two types of business in the plan. In these cases, the owner is the person who has the account, and a customer is a person who buys from the business.

Petra (master / chief of staff) #

Petra is the only bot that speaks to the owner. These cases test her alone.

Petra and Machu (research) #

The owner asks Petra. Petra gives Machu the task. Machu returns the findings with their sources. Petra tells the owner.

Petra and Angkor (website and menu builder) #

The owner asks Petra for a website. Angkor builds it. Petra shows a preview link in the chat. Petra publishes the website only after the owner approves it.

Petra and Kyoto (support) #

Kyoto answers the messages of the customers of the business. Petra tells the owner what occurred and brings the approvals.

Petra and Greenwich (Google Maps) #

Greenwich looks after the business's Google Maps listing. Anything the public will see goes through Petra to the owner for a yes first.

Petra and the cards in the chat #

The owner speaks to Petra in the chat, and Petra shows cards in the chat. Moe said that this use case is very important.

The judgement of Petra #

These cases show how Petra decides. In each case, Petra must make a decision that a fixed rule cannot make, and she must give her reason. Part 4, "How Petra decides", gives the sequence of questions.

Petra and the signals #

Petra reads signals and confirms them. She does not react to each piece of information. Moe gave the examples for these cases.

The whole squad #

These cases test the promise: a company can launch with tensquads.

How to measure. Run each chosen case 5 times. A case passes when all 5 runs meet "Success looks like". Where a row gives no number, the tensquads team judges it against the written line.

13. Research and sources #

This part contains the research behind the design. It shows what each reference says and what we take from it. The design is in Parts 4 to 9. Moe added all the topics.

Framework: everything is a plugin #

tensquads already has the base: a cordis core, one plug-in per domain area, skill updates as plug-in swaps. What it lacks is the tests that stop drift. DeepSeek's projects get their discipline from tests, not from the plug-in idea alone.

What it means in DeepSeek Harness (DSH). There is no privileged core. The model adapter, tool registry, session log and agent loop are each a plug-in. Each service has one owner and one typed key. Every registration returns a disposer, so unloading a plug-in removes all it added. Composition is data, and one command prints the booted tree.

How they stop drift. A dispose test for every registry. A boot test for each plug-in. Recorded-session snapshots. Config that is validated and fails loudly at load. Tests that check the docs match the code. The rule "what the model sees is logged".

Philosophy (dsh-superagent). Take little human attention and give much value. Act only on request or by a written rule. Ask one question at a time. Stop by impact. Report honestly. Few concepts, few settings. Start narrow.

Borrow, in order

Does not fit. DSH and DS-Bot assume one long-lived process with local files and SQLite. A Durable Object hibernates, so plug-ins there must rebuild from stored state. Their hot reload watches files; tensquads swaps by bus message. DSH lets users patch composition; decision 18 forbids customer version pinning.

Not read. The cordis primer on DSH's docs site was blocked, so the cordis plug-in API itself is unverified here.

Bots studied: what to borrow #

The three products confirm the tensquads shape: one master that talks, specialists that work, approvals before risky actions. The ideas worth taking are about reliability, not features.

Borrow

Do not borrow

• OpenBot's agents run with full access and no per-action approval. This conflicts with the autonomy limits.

• Rerun's agents can install their own tools and run an unconfined shell. An agent that grants itself tools bypasses the code check.

• OpenMausBot lets many bots answer the user. In tensquads only Petra speaks.

OpenMausBot, a closer read. It is the nearest relative of tensquads: it runs bots on boat.dev cloud computers and uses Jev to route messages.

• Routing with a decision model. A room set to Auto asks the model which bot should answer. It accepts the answer only above a 0.6 probability, a threshold measured against Jev. Every answer is validated before use.

• It fails open. With no key, a timeout, an error or an unsure answer, the room does what it would have done without the model: the lead answers. In tensquads the lead is Petra.

• Provider is swappable. Jev, Cloudflare Workers AI or OpenRouter sit behind one seam. tensquads already runs on Cloudflare, so Workers AI is a third Decider candidate.

• A decision log. One row per call: seam, provider, choice, top probability, margin, latency, tokens and a hash of the state. No message text.

• A live eval. 53 labelled messages replay against the live model for about $0.002 a run. This is the shape of the trial tensquads needs.

• Triggers. Schedules, webhooks and app events ("when an email from Acme arrives") share one queued executor and one run history.

• Teams as one Markdown file. A team installs from a file after a review screen. Connections stay off, routines arrive paused, and the file never carries keys, chats or memory.

Rerun, a closer read. Its pitch is the tensquads pitch: say what you need in plain words, and a Chief of Staff builds the team.

• The Chief of Staff covers for the owner. It interviews the owner, hires the coworker for each job, and answers coworkers by the owner's rules while the owner is away. This is Petra plus the Rules screen.

• Ready-made coworkers. Templates people hire on day one: inbox and calendar, data questions with a weekly KPI report, review and competitor watch with drafted replies, prospecting, social posts, and late-invoice chasing. Review watch fits Greenwich; invoice chasing fits the Accounting bot on the roadmap.

• One board. Every coworker, every machine and every running task on one screen. Approvals appear inline in chat.

• A screen you can watch. Each coworker has a browser the owner can watch and take over.

• Each coworker is a folder. A soul file, skills, and a memory that grows with each task, all readable Markdown.

• Architecture. One engine per workspace, with Postgres for data. The same shape as one Durable Object per account with Neon.

Not read. The OpenMausBot site redirects to a host this session cannot reach. Its findings come from its GitHub repository.

Memory #

What the references say

• Anthropic: memory has four layers. Session transcripts are the base. Notes are what the agent chose to keep. Above them sit structures such as a wiki. On top is a small index loaded into every session. An offline pass ("dreaming") checks notes against transcripts and corrects them.

• Anthropic's advice: store what the agent worked out, not what it can re-read. Record how each fact is known. Keep the top layer small. Give each record one writer: a shared table with many writers kept 41 of 57 facts; one page per contract with one writer kept 57 of 57.

• OpenClaw: plain Markdown files, no hidden state. Owner preferences, curated facts and daily notes are separate files. Only the first two load at session start; the rest is reached by search. Search mixes keyword and vector, weighted by recency and importance. Every entry carries its origin, set by the system. Untrusted content can never be promoted. A nightly job is the only writer of the curated file.

Routing #

What OpenClaw does

• Each agent has its own workspace, credentials and session store.

• A binding maps an inbound message (channel, account, sender) to one agent. The most specific binding wins. Within a tier, the first in config order wins.

• With no match, the message goes to a named fallback owner, or stays undispatched and is dead-lettered after 24 hours. Routing never picks the first agent in the list.

• Bindings route inbound messages only. Delegation is the model's choice: a coordinator spawns specialists from an allow list.

• Its team preset matches tensquads: the coordinator is the human's contact; specialists return work and do not delegate further.

• Agent-to-agent access is open by default.

Decisions: Jev #

Speed and cost. These are the vendor's own numbers; we have not tested them.

TypeSafe says this example is "on the higher end of real world gains". It gives no accuracy number.

There are two candidates. Jev is from TypeSafe. Sage is from Levanto and does the same job. The Capacitr case study you sent is about Sage, not Jev. Capacitr put Sage in front of eight money-moving tools and reported under 100 ms per decision and no wrong blocks in 152 audited calls. Sage accepts Jev's request format, so we can test both with the same code.

Notes for builders

• The Decider port takes one question and returns one answer. It needs an async form that takes several questions.

• Jev has four question types: Choice, Score, Noul (yes or no, as a probability) and Box (find something in an image). Sage has Yes/No, Choice, Scale, Sort and Tags, and returns null when unsure.

• Both use POST /v1/systemone. Jev costs $0.042 per million input tokens; output is free.

• The Decider must fail safe. On an error, a timeout, or Sage's 402 when usage runs out, the task goes to Petra or the owner.

• Jev 1.14's image, box and long-context features are experimental. Do not use them in production.

• OpenMausBot accepts a Jev routing answer only above a 0.6 probability. It also supports Cloudflare Workers AI as a third provider.

Sources #

Framework

• dsh-superagent-prototype: philosophy, domain, execution, architecture, cookbook

• deepseek-harness: architecture, AGENTS.md, testing

• cordis: core README

• DS-Bot: AGENTS.md, README, and the steward, parts, groups and chat-index source files

Bots

• Rerun: README, CLAUDE.md, engine README, INSTALL.md

• OpenMausBot: AGENTS.md, team sharing, decision model, MCP server docs

• OpenBot: home, teams, pricing, channels post, and its repository

Memory and routing

• Components of agent memory, Anthropic

• OpenClaw: memory, memory architecture, multi-agent

Decisions

• TypeSafe: Don't call it a decision model, Jev 1.14, launch post, home

• Levanto: Capacitr case study, pricing

Could not open

• The OpenMausBot site (redirects to mausbot.com); its repository README and decision-model doc were read instead

• The cordis primer on the DeepSeek Harness docs site

• TypeSafe's docs and pricing, and Levanto's docs

• Rerun's docs site

Also read: TypeSafe docs (introduction, models, confidence, index), Levanto docs (introduction, pricing, SystemOne API), and the full READMEs of Rerun and OpenMausBot.

14. Open questions #

Each question needs an answer before we build the related feature. When a question has an answer, the answer goes to Part 11, Decisions.

There are no open questions now.