Repository navigation
Visual Guide
Use these diagrams to understand where .SYSTEMX keeps information and how
work moves between people, AI tools, and saved records. They describe the
existing format; opening a diagram or folder does not start an agent.
Text equivalent: establish the objective and constraints; plan tasks and
acceptance; perform scoped work; collect actual checks and evidence; have Agent 0
review the result; save accepted facts and the next action. A later session
loads that state and continues. Subagents are optional, and a project owner may
review completion. Workers and the coordinator write the relevant records;
.SYSTEMX does not automatically capture every interaction.
Follow Daily workflow for the commands and Subagent processing for the runtime sequence.
flowchart LR
Root[".SYSTEMX"] --> Global["GLOBAL/CONTEXT.md"]
Root --> Plan["PLAN/MASTER-PLAN.md"]
Root --> Work["WORK"]
Work --> Tasks["TASKS.json: task authority"]
Work --> Focus["FOCUS.json: selected objective"]
Work --> Status["Generated status views"]
Root --> Current["CURRENT.md: generated focus view"]
Root --> Memory["MEMORY"]
Memory --> Facts["PROJECT.md: reviewed facts"]
Memory --> Sessions["sessions/: dated checkpoints"]
Root --> Agents["AGENTS"]
Agents --> Registry["REGISTRY.json: recorded roles"]
Agents --> Notes["agent.0 and registered worker memory"]
Root --> Config["project.json: configured commands"]
Root -. managed install .-> Selected["INSTALLATION.json: selected defaults"]
Root -. managed install .-> Cache[".systemx/: retained releases and operation records"]
This tree shows the major records, not every template file. Dashed branches are
managed-installation state. The canonical outer folder is .SYSTEMX. The
nested .SYSTEMX/.systemx/ manager cache has a different purpose from an optional
sibling alias .systemx -> .SYSTEMX. See Exact casing and alias.
Text equivalent: Global stores shared project context; Plan stores outcomes; Work owns task state and current focus; Memory stores accepted knowledge and checkpoints; Agents stores role records and individual notes. Current and status pages are generated views. Project configuration holds explicit commands. Managed installation metadata selects retained default instructions and tools.
The reusable template starts blank with only Agent 0. Worker entries appear when a project deliberately registers them. A role's existence does not establish that a corresponding runtime worker is active.
flowchart TD
Owner["User objective and project constraints"] --> A0["Agent 0 plans and coordinates"]
A0 --> Ledger["WORK/TASKS.json"]
Ledger --> Packet["Bounded assignment with acceptance and dependencies"]
Packet --> Harness["Authorized tools in the AI harness"]
Harness --> Result["Scoped work and actual evidence"]
Result --> Review["Agent 0 reviews and integrates"]
Review -->|Accepted or returned for work| Ledger
Review -->|Reviewed durable facts| Memory["Project memory"]
Ledger --> Views["Generated task-status views"]
Ledger --> Current["Generated CURRENT.md"]
Focus["WORK/FOCUS.json"] --> Current
Review --> Checkpoint["Saved checkpoint and exact next action"]
Checkpoint -. referenced by .-> Focus
Current --> Resume["Next session loads records and rechecks live state"]
Memory --> Resume
Resume --> A0
Text equivalent: Agent 0 turns an accepted objective into ledger tasks. A scoped packet goes to authorized harness tools. Actual results return for review. Agent 0 updates the task record and promotes verified facts. Focus selects the next work and may link an existing checkpoint. A new session reads those records and rechecks observations that can change.
The arrows describe responsibilities, not an automatic data pipeline. CLI task writes update history and regenerate views. Checkpoints and shared-memory promotion require explicit writes by the assistant or project owner. Full acceptance criteria and original evidence remain available when bounded packets omit detail. See Planning and memory.
- Subagent processing: delegation decisions and the assignment, runtime, result, and review sequence.
- Advanced use cases: a feature dependency graph and practical examples for engineering, research, incidents, shared folders, chat handoffs, and more than one project.
- Technical Guide: installation state, writer locks, scale limits, and requirements for future adapters.
The logo is the exact .SYSTEMX wordmark with a branching-folder symbol.
The visual brand stands alone. Maintainer attribution stays separately in the
repository's project information and the wiki footer.
Download the logo PNG or workflow PNG. The raster artwork was created with the built-in imagegen tool; its final edit prompts are recorded with the assets. The white backgrounds preserve the intended contrast in light and dark documentation pages.
The technical diagrams are editable Mermaid code stored in these wiki pages. GitHub supports Mermaid in Markdown files and wikis; see GitHub's diagram guide. Text equivalents accompany the diagrams for readers or tools that do not render them. When updating a diagram, update its explanation and verify rendering.
flowchart TD
Root[".SYSTEMX: shared tools and standards"] --> Plan["Workspace Global, Master Plan, Agent 0"]
Root --> Registry["Projects/REGISTRY.json: explicit selection"]
Registry --> A["Project-A/.SYSTEMXP"]
Registry --> B["Project-B/.SYSTEMXP"]
A --> AWork["A: context, plan, ledger, focus"]
A --> AMemory["A: Agent 0, workers, memory, decisions"]
B --> BWork["B: context, plan, ledger, focus"]
B --> BMemory["B: Agent 0, workers, memory, decisions"]
No child contains another .SYSTEMX. Each branch of this diagram is a record
scope, not a process tree. Shared version pins live in the outer installation.
Follow SYSTEMX PROJECTS for setup and execution boundaries.
flowchart TD
Objective["Accepted idea and objective"] --> A0["Agent 0: scope and next bounded action"]
A0 --> Work["Authorized work and relevant checks"]
Work --> AX["Agent X: event time, revision, actor, evidence"]
Work --> Boundary["Completion boundary or requested review"]
Boundary --> Changed{"Source, evidence, or policy changed?"}
Changed -->|No| Reuse["Reuse existing scorecard"]
Changed -->|Yes| AZ["Agent Z: same 100 versioned questions"]
AX --> AZ
AZ --> Score["Scorecard, unknowns, evidence, delta"]
Score --> Decision["Agent 0 or user: acceptance decision"]
Reuse --> Decision
Decision -->|Criteria met| Stop["Accept and checkpoint"]
Decision -->|Concrete remaining gap| Next["Define the next bounded action"]
The final gap node is a decision point, not an automatic execution loop. Scores and due items never launch jobs or reopen tasks. See Agent X and Agent Z for record semantics and authority boundaries.