Promptware OS × BMAD Boot (MVP POC) + Root Switching #5

Status: MVP POC design draft (intentionally simple).
Principle: PromptwareOS = bootloader + kernel + VFS + conventions. Everything else is Application Layer.

0. What we’re optimizing for

Core value of PromptwareOS

• A one-liner bootloader in AGENTS.md
• A robust, small kernel (OS-level laws + primitives)
• A cloud-native loading model (GitHub-first in MVP)
• A Linux-style handoff: boot OS → os_chroot (derived from init) → run application init

What PromptwareOS should not become

• A giant repo of everyone’s agents
• A place that needs PRs for user application agents
• A workflow framework that competes with BMAD

PromptwareOS should become more powerful by doing less.

1. Minimal MVP POC scope

MVP POC goal

Prove: PromptwareOS can boot and then load a BMAD web bundle as init with zero local installation.

What we do not build in MVP POC

• os/modules/* system
• expansion pack discovery
• content patching/overlay
• format parsing

“Any format is text” policy

For MVP POC, all resources are treated as OS prompt text.

• Markdown / TXT / YAML / JSON / XML are all “ingestable text.”
• If a user points init to it, they accept that it’s usable as prompt content.

2. Kernel Layer primitives (MVP)

Note: “Kernel Layer” vs “Application Layer” is a portability contract, not a security boundary.

PromptwareOS kernel already defines:

• os_resolve(path) — VFS: Virtual Path → Real URL
• os_ingest(path) — load text into active context
• os_invoke(tool_url, args) — run remote tools ephemerally

Add one explicit primitive: os_chroot(new_root) (boot-intended)

os_chroot(new_root)

• Function: Change the VFS root mount (/) to a new GitHub raw root.
• Effect: After chroot, /anything resolves against new_root.
• Invariant: Kernel Layer laws remain; only the root mapping changes.
• Intended use: boot stage (handoff from OS root → application root). Advanced users may call it later.

3. Bootloader config (GitHub-first)

Bootloader inputs

Keep it minimal and deterministic:

• root: official PromptwareOS root (GitHub raw)
• kernel: kernel path (relative to root)
• init: application init (can be a relative path or a full GitHub raw URL)

Example (conceptual):

version: "0.1"
root: "https://raw.githubusercontent.com/ShipFail/promptware/<ref>/os/"
kernel: "/kernel.md"
init: "https://raw.githubusercontent.com/<org-or-user>/<repo>/<ref>/<path>/init.txt"  # or a BMAD bundle URL

Interpretation (simple and strict)

1. Kernel loads from root + kernel

2. Kernel decides whether to os_chroot() based on init:

   • If init is a full GitHub raw URL pointing to a different repo/ref than root, then:

     • derive Application Root = https://raw.githubusercontent.com/<org>/<repo>/<ref>/
     • call os_chroot(Application Root)
     • rewrite init to the remaining path within the repo (e.g. /<path>/init.txt)

   • Otherwise:

     • keep current root (no chroot)

3. Kernel resolves init against the current root and ingests it

4. Handoff to Application Layer

This matches your intent: no extra route field; the application root comes from init.

4. fstab concept (kept, but simple) (kept, but simple)

What fstab is for

fstab is the user-space way to declare additional mounts in a deterministic way.

Where fstab lives

• OS root may have its own fstab (Kernel Layer mounts) — optional.
• Application root has its fstab (Application Layer mounts) — recommended.

No overrides rule

• Kernel reads OS fstab before os_chroot (if present).
• After os_chroot, kernel reads application fstab.
• If application fstab attempts to mount over an existing mount point, kernel panics.

Minimal fstab format (YAML)

version: "0.1"
mounts:
  - mount: "/modules/bmad/"
    url: "https://raw.githubusercontent.com/bmadcode/bmad-method/<ref>/"
  - mount: "/lib/"
    url: "https://raw.githubusercontent.com/<user>/<repo>/<ref>/lib/"

MVP POC note: fstab is a design target, but not required for the first BMAD-bundle boot.

5. The simplest BMAD boot (Bundle-first POC)

Claim

Yes — bundle-first BMAD boot is the easiest part.

How it works

• Set init to the BMAD bundle file URL (GitHub raw).
• Kernel will os_chroot() into the bundle’s repo root (derived from the URL) and ingest the bundle as init.
• Kernel ingests that file as prompt text.

That’s it.

What PromptwareOS does not do here

• It does not interpret “bundle structure.”
• It does not install directories.
• It does not manage outputs.

The LLM user environment writes outputs to the local workspace; PromptwareOS is only the loader/kernel law layer.

6. What this proves

If the bundle-first POC works, we’ve proven:

• PromptwareOS can boot reliably from an official OS root
• PromptwareOS can os_chroot into a user/application root
• PromptwareOS can ingest arbitrary text payloads as init
• BMAD (or any system) can be booted by URL without installation

This is the “cloud-native agent OS” proof.

7. What comes next (after POC)

Next milestone A — fstab mounts become real

• Use fstab to mount BMAD + user libraries simultaneously
• Keep strict VFS semantics

Next milestone B — friendly names (optional sugar)

Support pm@bmad or agent@module only after fstab/manifest exists.

Next milestone C — dependency-aware systems (optional)

Only if needed: load multi-file workflows with strict path resolution.

Discussion points for the next iteration

1. Should route accept only GitHub raw roots in MVP, or any HTTPS root?
2. Where should the application fstab live by convention: /fstab.yaml, /.promptware/fstab.yaml, or /etc/fstab.yaml?
3. Should os_chroot() be callable only during boot, or also later (advanced)?