Visual Guide

Visual Guide

These diagrams explain the .SYSTEMX format, including Agent 0, Agent X, Agent Y, Agent Z, named .SYSTEMXP projects, execution waves, and shared-source handoffs. The live Tier 2 diagram below adds Agent Alpha, ten AUTOBOT detail specialists, and local DATA for 1.10.0-alpha.2. The raster poster retains its examined alpha.5 CLI/.SYSTEMXP baseline; it does not depict this new Tier 2. The full-system poster shows the installed management CLI, trusted local launchers, configured application tools, the task-selected external CLI/PR lane, and the exact named .SYSTEMXP path. Use the Agent Y workflow for its detailed authority gates and recovery limits. The arrows show responsibilities and evidence flow. The folder does not launch workers or install a transport when you open a diagram.

Four environment cards

Use-case infographics provides separate 4K cards and step-by-step text for ChatGPT + Drive, Codex + GitHub, Dots / Codex Cloud, and Codex / Copilot CLI on a local drive. The source assets travel in .SYSTEMX/MEDIA.

Tier 2: AUTOBOT detail and local DATA

flowchart TD
    Scope["Select one root .SYSTEMX or named child .SYSTEMXP"] --> A0["Agent 0: plan, task routing, integrate, accept"]
    A0 --> Native["Authorized harness workers / configured project tools"]
    A0 --> Y["Agent Y: optional selected external CLI / draft PR"]
    A0 --> Alpha["Agent Alpha / AGENTA.MD / optional agent.a"]
    X["Agent X: observed events and time"] -->|"explicit detail request"| Alpha
    Y -->|"explicit detail request"| Alpha
    Z["Agent Z: fixed evidence review"] -->|"explicit detail request"| Alpha
    Tools["Explicit Tools step / caller tools"] --> Alpha
    Alpha --> Match{"Same selected inputs and request?"}
    Match -->|"yes"| Reuse["Reuse existing request/result and original evidence time"]
    Match -->|"changed / new"| Select["Select only relevant fixed specialist slots"]
    Select --> Panel["Design.MD · Soul.MD · Memory.MD · Rules.MD · Research.MD<br/>Brand.MD · Media.MD · Tokens.MD · Data.MD · Archive.MD"]
    Panel --> Detail["Bounded detail packet / explicit request and completion"]
    Reuse --> Detail
    Detail --> A0
    Native --> Evidence["Original project evidence; canonical task ledger stays with Agent 0"]
    Y --> Evidence
    Evidence --> X
    Evidence --> Z
    Panel -. "safe references only; no automatic scan" .-> Data["Selected DATA: TEMP / LARGE / IMPORTS / RESEARCH<br/>ASSETS / EXPORTS / CACHE / ARCHIVE"]
    Data --> Audit["Exact tracked scaffolds; payloads Git-ignored by default; data audit"]

Loading

Text equivalent: choose one scope and its records first. Agent 0 owns the objective/plan/task ledger and acceptance; X records actual time, Y is the optional external CLI channel, and Z reviews fixed questions. An explicit selected request from these roles or Tools reaches Agent Alpha, which returns only relevant detail from the ten fixed Markdown slots. An unchanged completed request reuses its original result/evidence time. Changed inputs identify stale historical detail and justify a new bounded request. No arrow starts a worker, a recursive check, a model call, or background synchronization. Specialist rules are lower-authority project data. Raw/private/large payloads stay in selected DATA; safe references connect them to the panel. Root/child panels and DATA never inherit each other. See AUTOBOT and Agent Alpha and Local DATA storage.

Full-system overview

Download the portable 4K JPEG · View the 4K PNG · Read the complete text equivalent · Generation and correction prompts

The built-in imagegen edit returned a 1672 × 941 native image. The public PNG and portable JPEG were exported to 3840 × 2160 using macOS sips; the JPEG uses quality 80. Resizing adds canvas pixels rather than native detail. The current portable JPEG is 1,867,015 bytes, SHA-256 cc09f9cde7aba3bb77c109257a937b031254d599b81479ad96b05909a617e1b1. The canonical web PNG is 7,334,619 bytes, SHA-256 48d0a9f413da3d30c8f6853f8fa3d30ce2639c2bf4a300edae1680b322065e2e. Both values were independently read back from the exact public alpha.5 tag ZIP. The asset metadata records exact-byte hashes and export method. The JPEG travels in the installed .SYSTEMX/MEDIA/Infographics/ folder with its portable text equivalent.

The new portable map uses systemx-cli-projects-4k.jpg with companion Reference/cli-projects.md. The installed additive update adds those new files and preserves an older local systemx-full-system-4k.jpg and its text; that retained file continues to describe its earlier baseline. The current public template retains this alpha.5 full-system map plus the four frozen use-case cards; the live Tier 2 diagram above documents the new AUTOBOT/DATA addition. The canonical web PNG URL stays stable. Pin a tagged URL for frozen artwork.

The alpha.5 poster connects the standard locations, four roles, logs, and toolchain. Agent 0 assigns and accepts work, Agent X tracks observed time, Agent Y returns a selected CLI/worktree/PR handoff, and Agent Z reviews matching evidence. Numeric subagents are scoped harness workers. X/Y/Z records appear after explicit role activation; installation metadata appears after installation. Use the linked guides for exact commands and permissions.

Section	How information moves
Shared context	Read relevant instructions, Global context, Master Plan, reviewed memory, and checkpoints.
Agent 0 and workers	Assign bounded tasks; workers return results and original evidence to the integration owner.
Canonical work	Update WORK/TASKS.json and focus; generate current and status views from those records.
Agent X	Record actual events, actor/time/revision/evidence, retry keys, and due items. Scheduling execution stays external.
Agent Y	Delegate an authorized task to one selected installed CLI in an isolated worktree; return changed paths/commit and an opt-in draft PR. Agent 0 runs/cites independent project checks.
Agent Z	Assess the fixed 100 questions with evidence; return findings to Agent 0/user for acceptance or a concrete next task.
CLI and Tools	systemx supplies installation/record routing; reviewed SYSTEMX.sh/SYSTEMX.ps1 launch local defaults; Git/gh/Python and configured check/dev/build/deploy commands supply actual execution. Providers remain separately installed.
App / IDE workers	The harness supplies models, native subagents, processes, permissions, and application tools. Agent Y's external CLI is a separate process/context.
SYSTEMX PROJECTS	Select .SYSTEMX/Projects/Project-A/.SYSTEMXP or another named child explicitly; outer tools/defaults are shared, child context/plan/ledger/agents/evidence remain scoped.
Defaults and recovery	Use selected versions, additive updates, audits, and backup/restore receipts.

The internal .SYSTEMX/.systemx/ cache is distinct from an optional sibling .systemx → .SYSTEMX alias. Cloud/Drive/Git transport requires actual authorized access and verified snapshots; a URL alone neither grants access nor synchronizes records. Review scores do not authorize work or launch an automatic rebuild loop. See CLI and Tools, technical details, commands, Agent X, Agent Y, Agent Z, and project routing.

The retained CLI/.SYSTEMXP raster map shipped with alpha.5. For a fixed artwork revision, use the tagged 4K PNG; main and this wiki can evolve in later releases.

CLI, tools, and named project routing

flowchart LR
    Human["Human / authorized AI app or IDE"] --> SX["systemx: installed management CLI"]
    Human --> Local["Reviewed SYSTEMX.sh / SYSTEMX.ps1"]
    SX --> Outer[".SYSTEMX: shared selected defaults and tools"]
    Local --> Outer
    Outer --> Root["Explicit --root: workspace records"]
    Outer --> Registry["Projects/REGISTRY.json"]
    Registry --> A["Projects/Project-A/.SYSTEMXP"]
    Registry --> B["Projects/Project-B/.SYSTEMXP"]
    A --> A0["Scoped Agent 0: assign / integrate / accept"]
    A0 --> Native["App / IDE bounded workers"]
    A0 --> Y["Agent Y: selected Codex / Copilot / configured CLI"]
    Y --> Git["Task worktree / Git / opted-in draft PR via gh"]
    A0 --> Tools["Configured check / dev / build / deploy"]
    Native --> Evidence["Scoped evidence / Agent X time / Agent Z review"]
    Git --> Evidence
    Tools --> Evidence

Loading

Text equivalent: choose the outer installation before choosing a child. The installed systemx projects --target OUTER_DIR -- ... --project Project-A command selects shared defaults and that child's records. A reviewed local launcher offers the same scoped runtime. Native app workers and Agent Y's external CLI are distinct execution choices; Git/gh and configured project commands remain explicit tools with their existing authority. A child .SYSTEMXP is a record scope, never a nested installation. Tool map.

Shared context, work, time, and review

Text equivalent: keep the researched objective and constraints in shared context; Agent 0 selects and integrates bounded work; the harness supplies actual tools and workers. Agent X records meaningful times, attempts, revisions, and evidence. When selected, Agent Y runs one bounded external CLI task and returns its worktree/commit and optional draft PR for independent project checks. Agent Z reviews the fixed policy at a completion boundary or on request, reusing unchanged proof. Agent 0/user accepts against the original criteria or identifies a concrete gap. Save canonical tasks, generated views, reviewed facts, and a checkpoint. A later authorized turn reads the relevant current state.

This is the practical shared-brain metaphor: useful project knowledge can accumulate across turns. It is not model training, AGI, guaranteed improvement, or an automatic endless work loop. Turn protocol.

From a researched brief to delivery

Text equivalent: wave 0 researches the brief; wave 1 verifies shared foundations/contracts; wave 2 performs independent scoped tasks; wave 3 integrates user journeys; wave 4 verifies and reviews; wave 5 delivers within authority and checks the actual target. Each transition requires the milestone's evidence. Agent X records events throughout; Agent 0 owns plan/task consistency. An independent wave task may use Agent Y’s selected CLI lane under the same scope, concurrency, cost, and acceptance limits as the app’s workers.

Phases and waves are planning conventions, not extra commands or schema fields. See the 20-page app walkthrough for the route matrix, research and execution prompts, acceptance gates, and alternative project types.

Multiple chats and bots, one record authority

Text equivalent: several readers/workers can use a selected snapshot. One owner reconciles accepted changes to each canonical record scope. Git, Drive, a connector, or a cloud snapshot adapter supplies transport. Verify saved revision, conflicts, and readback before the next session writes. A URL does not itself grant access, persist changes, or synchronize concurrent edits. See shared workspaces, clouds, chats, and bots.

Folder and record tree

flowchart LR
    Root[".SYSTEMX"] --> Global["GLOBAL / shared context"]
    Root --> Plan["PLAN / Master Plan"]
    Root --> Work["WORK / canonical tasks and focus"]
    Work --> Views["Generated CURRENT and six status views"]
    Root --> Memory["MEMORY / accepted facts and checkpoints"]
    Root --> Agents["AGENTS / 0, optional X/Y/Z/A, registered workers"]
    Root --> Auto["AUTOBOT / ten fixed detail slots + AGENTA.MD"]
    Root --> Data["DATA / exact tracked scaffolds; ignored payloads"]
    Root -. role activation .-> Events["EVENTS / occurrence time and due items"]
    Root -. role activation .-> Jobs["AGENTS/agent.y/JOBS.json / external CLI channels"]
    Root -. role activation .-> Reviews["REVIEWS / policy, requests, scorecards"]
    Root --> Config["project.json / explicit command arrays"]
    Root -. managed install .-> Selected["INSTALLATION.json / selected defaults"]
    Root -. managed install .-> Cache[".systemx / retained releases and operation logs"]

Loading

Text equivalent: Global and Plan preserve purpose; Work owns task state and focus; Memory holds reviewed knowledge; Agents holds scoped role notes. Activated X/Y/Z records add event/due ledgers, CLI job channels, and fixed-policy review records. Configuration selects explicit commands. Managed metadata selects versioned defaults. The internal .SYSTEMX/.systemx/ cache differs from the optional sibling alias.

The public distribution stays blank with only Agent 0 registered. New role activation preserves existing records and starts no runtime process. Generated views come from canonical records, not independently edited status lists. Standard format · Exact casing.

Named project scopes

flowchart TD
    Root[".SYSTEMX / shared tools and selected defaults"] --> Outer["Portfolio Global, Master Plan, Agent 0"]
    Root --> Registry["Projects/REGISTRY.json / explicit selection"]
    Registry --> App["WebApp/.SYSTEMXP"]
    Registry --> Research["Research/.SYSTEMXP"]
    Registry --> Bot["BotOps/.SYSTEMXP"]
    App --> AppRecords["App context, tasks, memory; optional X/Y/Z and AUTOBOT/DATA"]
    Research --> ResearchRecords["Research context, tasks, memory; optional X/Y/Z and AUTOBOT/DATA"]
    Bot --> BotRecords["Operations context, tasks, memory; optional X/Y/Z and AUTOBOT/DATA"]

Loading

Text equivalent: one outer installation provides defaults, while each named child owns separate context, plans, tasks, and memory. X/Y/Z activation is scoped. The supported path is .SYSTEMX/Projects/NAME/.SYSTEMXP; a nameless Projects/.SYSTEMXP and nested .SYSTEMX installations are unsupported. No scope or role is a process tree or an authentication boundary. SYSTEMX PROJECTS.

Reuse a review or assess a real change

flowchart TD
    Boundary["Completion boundary or requested review"] --> Match{"Matching report exists<br/>and inputs unchanged?"}
    Match -->|Yes| Reuse["Reuse saved scorecard and evidence"]
    Match -->|No| Assess["Agent Z / same versioned 100 questions"]
    Assess --> Report["Scorecard / unknowns / evidence / delta"]
    Reuse --> Decision["Agent 0 or user / original acceptance criteria"]
    Report --> Decision
    Decision -->|Met| Done["Accept and checkpoint"]
    Decision -->|Concrete gap| Next["Next bounded action or real blocker"]

Loading

Text equivalent: review when needed, reuse identical inputs, and compare only matching subjects/policies. Changed policy requires a new baseline. The acceptance owner chooses completion or a bounded next step. Neither a score nor a due item automatically reopens tasks, executes jobs, or repeats the pipeline. Agent X · Agent Z · 100 questions.

Diagram sources, downloads, and accessibility

The brand is the standalone .SYSTEMX wordmark. Maintainer attribution stays separate in project information. The original imagegen logo remains current. The comprehensive full-system poster is generated raster artwork with a saved prompt and text equivalent. Three focused workflow diagrams are rendered from editable Mermaid sources, with PNG previews and SVG exports in the repository's asset directory. The full-system poster and the three focused Mermaid diagrams were refreshed for Agent 0/X/Y/Z in the examined alpha.5 baseline. The live wiki Tier 2 diagram adds Agent Alpha/AUTOBOT/DATA for 1.10.0-alpha.2. The earlier six-step raster illustration and four environment cards are historical media; use the current poster and Agent Y CLI/PR workflow for current behavior.

Diagram	Editable source	Vector	Raster
Full-system overview	Imagegen prompt	Raster artwork	View the 4K PNG · Portable 4K JPEG
Shared-context coordination	Mermaid	SVG	PNG
Project waves	Mermaid	SVG	PNG
Shared workspace	Mermaid	SVG	PNG

Text equivalents and alt text accompany the diagrams. Color is not the sole indicator of meaning. Mermaid source also remains readable when a viewer cannot render it. Update the diagram, explanation, and exports together when behavior changes. GitHub's diagram documentation.

Four-role delivery gates

flowchart TD
    Context["Selected scope, Global context, Master Plan, TASKS.json"] --> A0["Agent 0: assign, integrate, verify, accept"]
    A0 --> App["Harness-native bounded workers"]
    A0 --> Y["Agent Y: task-selected installed CLI"]
    Y --> Local["Pinned executable; isolated worktree; scoped commit"]
    Local --> Draft["Optional authorized draft PR"]
    App --> Checks["Agent 0: original project check evidence"]
    Local --> Checks
    Draft --> Checks
    Checks --> Z["Agent Z: matching 100-question review"]
    Z --> Accept["Agent 0/user: criteria met or concrete gap"]
    Accept --> Ready["Accepted done + unchanged base: separate PR-ready"]
    Accept --> Cancel["Recorded cancelled: separate PR-close; retain work"]
    Ready --> External["Separately authorized merge outside Agent Y"]
    External --> Cleanup["Merged + accepted + exact owned head: verified bundle then cleanup"]
    A0 -. observations .-> X["Agent X: occurrence/recording time, revision, original evidence"]
    Checks -. observations .-> X
    Cleanup -. observations .-> X

Loading

Text equivalent: the canonical ledger remains under Agent 0. App workers and Agent Y are alternative bounded execution paths; they share one project budget. Y chooses a provider per task, pins the local executable, and returns a worktree and scoped commit. An opted-in draft PR may exist before independent project checks. X records observations without accepting tasks or running a scheduler; Z reviews evidence without granting authority. Agent 0/user records acceptance or cancellation. Ready, close, merge, and archived cleanup remain separate gates. A cancelled unmerged branch/worktree stays available for manual review. Agent Y has no merge command. Readback and recovery details are in Agent Y.