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 full-system poster includes the task-selected external CLI and pull-request channel. 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.

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 90. Resizing adds canvas pixels rather than native detail. 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 updated 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.
Toolchain	The harness supplies models, processes, permissions, and application tools; local entry points invoke configured work.
SYSTEMX PROJECTS	Select Projects/NAME/.SYSTEMXP explicitly; children share outer tools and keep separate records.
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 technical details, commands, Agent X, Agent Y, Agent Z, and project routing.

The current map ships with alpha.4. For a fixed artwork revision, use the tagged 4K PNG; main and this wiki can evolve in later releases.

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, registered workers"]
    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"]
    Research --> ResearchRecords["Research context, tasks, memory; optional X/Y/Z"]
    Bot --> BotRecords["Operations context, tasks, memory; optional X/Y/Z"]

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 have been refreshed for Agent 0/X/Y/Z. 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.