AI Bootstrap Guide — One-Prompt Backend Generation

The complete protocol for AI agents to scaffold, validate, build, and run a SysMARA project from one human prompt.

Overview

SysMARA's AI Bootstrap workflow turns a single natural-language product description into a fully working backend project. An AI agent reads the BOOTSTRAP.md protocol, generates all YAML specs, validates and builds the system, implements capability handlers, and starts a running server.

Human prompt → AI reads BOOTSTRAP.md → YAML specs → sysmara build → capability logic → tests → running server

Why This Works

Traditional frameworks encode architecture implicitly — in folder conventions, inheritance hierarchies, middleware chains, and tribal knowledge. An AI agent reading an Express.js codebase has to reverse-engineer the architecture from scattered files, comments, and patterns. It can guess wrong. It can violate constraints it never knew existed.

SysMARA inverts this. The architecture is the input, not the output:

• Machine-readable specs eliminate ambiguity. YAML is not prose. invariants: [email_must_be_unique] is a testable statement, not a suggestion in a README.
• Cross-validation catches mistakes before runtime. If a capability references a non-existent entity, sysmara build fails immediately.
• Module boundaries prevent architectural drift. The framework physically prevents module A from calling module B unless B is in A's allowedDependencies.
• Impact analysis tells the AI what its change will break. Before modifying an entity, sysmara impact entity <name> shows every affected node.
• The capability compiler generates boilerplate. Route handlers, test scaffolds, and metadata are generated from specs. The AI only writes business logic.

The One-Prompt Workflow

Step 1: Human Writes a Product Description

The human provides a natural language description. It can be as short as one sentence or as detailed as a full product spec. Examples:

• "Build a SaaS task manager with workspaces, tasks, and user roles"
• "Build an e-commerce API with products, orders, and inventory management"
• "Build a blog platform with posts, authors, tags, and moderation"

Step 2: AI Agent Reads BOOTSTRAP.md

The AI agent reads the BOOTSTRAP.md protocol, which contains the complete spec format, decision rules, and validation checklist. Prompt:

Read BOOTSTRAP.md in the project root. This contains the complete protocol
for bootstrapping a SysMARA project from a product description.
Follow it exactly.

Step 3: AI Generates All YAML Specs

The agent analyzes the product description and generates six spec files:

Read BOOTSTRAP.md. Based on this product description:

"[PASTE HUMAN'S PRODUCT DESCRIPTION HERE]"

Generate all SysMARA YAML specs in system/:
- system/entities.yaml — all domain entities with typed fields
- system/capabilities.yaml — all CRUD + domain operations
- system/policies.yaml — access control rules
- system/invariants.yaml — business rules
- system/modules.yaml — module boundaries and dependencies
- system/flows.yaml — multi-step workflows

Follow the spec format exactly as described in BOOTSTRAP.md.
Run `sysmara validate` to check for errors and fix any before finishing.

Step 4: Validate and Build

Run `sysmara build` to validate all specs and generate the system graph,
system map, route handlers, and test scaffolds.

If there are errors, read the diagnostic output, fix the YAML specs, and
rebuild. Repeat until `sysmara build` completes with 0 errors.

Step 5: Implement Capability Logic

The compiler generates stubs in app/generated/routes/. The AI implements actual business logic in app/capabilities/:

Implement the business logic for each capability.
For each capability in system/capabilities.yaml, create a file at
app/capabilities/<capability_name>.ts that exports a handle function.

The handle function receives a HandlerContext with:
- ctx.params — URL parameters
- ctx.query — query string parameters
- ctx.body — request body
- ctx.actor — authenticated user info
- ctx.capability — capability name

Return the output matching the capability's output spec.

Step 6: Write and Run Tests

Write tests for each capability in app/tests/.
Test scaffolds have been generated in app/generated/tests/.
Extend them with real test cases:
- Happy path for each capability
- Policy enforcement (unauthorized access should fail)
- Invariant enforcement (violating invariants should fail)

Run `npx vitest run` and fix any failures.

Step 7: Start the Server

Create server.ts in the project root.
Import SysmaraServer from @sysmara/core.
Register HTTP routes for each capability:
- create_* → POST
- get_* → GET with :id param
- list_* → GET
- update_* → PUT/PATCH with :id param
- delete_* → DELETE with :id param

Start the server on port 3000.
Verify with: curl http://localhost:3000/health

Complete One-Shot Prompt

If you want to do everything in a single prompt to your AI coding agent:

Read BOOTSTRAP.md. You are bootstrapping a new SysMARA project.

Product description:
"[PASTE DESCRIPTION HERE]"

Do the following in order:
1. Run `npx @sysmara/core init` to create the project
2. Analyze the product description and generate all YAML specs:
   - system/entities.yaml
   - system/capabilities.yaml
   - system/policies.yaml
   - system/invariants.yaml
   - system/modules.yaml
   - system/flows.yaml
3. Run `sysmara validate` — fix any errors
4. Run `sysmara build` — verify success
5. Implement capability handlers in app/capabilities/
6. Create server.ts with HTTP routes
7. Write tests in app/tests/
8. Run tests with `npx vitest run`
9. Start the server and verify /health responds

Follow BOOTSTRAP.md exactly. Use snake_case everywhere. Entities singular,
modules plural. Do not skip validation.

What Gets Generated

From a single prompt like "Build a SaaS task manager with workspaces, tasks, and user roles", the AI agent produces:

my-task-manager/
└─ sysmara.config.yaml
└─ server.ts
└─ system/
│   └─ entities.yaml        # user, workspace, task, workspace_member
│   └─ capabilities.yaml    # 13 capabilities (CRUD + domain)
│   └─ policies.yaml        # workspace_member_policy, task_owner_policy, admin_policy
│   └─ invariants.yaml      # email_unique, task_title_required, workspace_slug_unique
│   └─ modules.yaml         # auth, workspaces, tasks
│   ┌─ flows.yaml           # task_lifecycle flow
└─ app/
│   └─ capabilities/        # 13 capability handlers
│   └─ tests/               # test files
│   ┌─ generated/           # compiler output (routes, tests, metadata)
┌─ .framework/
    └─ system-graph.json
    ┌─ system-map.json

Spec Types at a Glance

How to Read a SysMARA Project

When encountering a SysMARA project for the first time, read in this order:

1. sysmara.config.yaml — project name, paths, database config
2. system/modules.yaml — the table of contents; what domains exist and how they relate
3. system/entities.yaml — the data model; every field, type, and constraint
4. system/capabilities.yaml — the API surface; what operations exist
5. system/policies.yaml — the access control model
6. system/invariants.yaml — the business rules
7. system/flows.yaml — multi-step workflows
8. Run sysmara doctor — verify project health

How to Modify a SysMARA Project

1. Understand the impact first. Run sysmara impact <type> <name> for anything you plan to change.
2. Modify the specs. Change the YAML files in system/.
3. Validate. Run sysmara validate to catch reference errors.
4. Build. Run sysmara build to regenerate everything.
5. Update implementations. Modify capability handlers if needed.
6. Test. Run tests to verify nothing broke.

Never modify app/generated/ directly — it gets overwritten on build.

Does This Actually Work?

Yes. We tested all three example prompts end-to-end. Here are the real numbers:

Every prompt, command, and output number is documented on the AI Prompts That Actually Work page.

When to Use SysMARA

Good Fit

• Multiple AI agents on the same codebase. When two or more AI agents (or AI + human) contribute to the same project, implicit conventions break silently. SysMARA specs are the single source of truth every contributor reads.
• Audit trails and enforced invariants. If your domain has rules that must never break (stock can't go negative, emails must be unique, state transitions must follow a lifecycle), declaring them in YAML means they are validated at build time, not discovered at runtime.
• Generated boilerplate. Route handlers, test scaffolds, and metadata files are generated from specs. The AI (or human) only writes business logic.
• Explicit architecture. Module boundaries, dependency rules, and capability contracts are declared, not implied by folder structure. New team members (human or AI) can read the system in minutes.

Not Ideal

• Small solo projects. If you are the only developer, you already know the architecture. The YAML specs add overhead without proportional benefit.
• Quick prototypes where YAML feels like overhead. If you need a throwaway demo in an afternoon, writing specs first slows you down. Use SysMARA when the project will live long enough for the specs to pay off.
• Projects with no AI involvement. SysMARA's primary value is making architecture machine-readable. If no AI agent will ever touch the codebase, a traditional framework with good documentation may be simpler.

Example Projects

Three complete example projects demonstrate the one-prompt workflow end to end:

• SaaS Task Manager — 5 entities, 15 capabilities, 5 policies, 6 invariants, 3 modules, 2 flows → 18 generated files
• E-Commerce API — 6 entities, 7 capabilities, 3 policies, 4 invariants, 4 modules, 1 flow → 21 generated files
• Blog Platform — 5 entities, 8 capabilities, 3 policies, 4 invariants, 3 modules, 1 flow → 24 generated files

Each includes the tested prompt, the exact commands, and concrete output numbers. See the AI Prompts That Actually Work page for details.