Standard Format

.SYSTEMX format contract

Beta prerelease: validate the selected version in your project. See the release policy.

SYSTEMX defines a reusable project operating format. It is a project-maintained convention, not a certification or an externally ratified industry standard. Documentation can be used without the CLI. The CLI validates the JSON records and generated views described here; it does not execute an agent runtime.

File and version conventions

• Put the complete .SYSTEMX directory at the host project root. Preserve exact path casing on every system; the stored folder name must be .SYSTEMX. A local lowercase alias may only route to that directory under the exact-case contract. Use UTF-8 text and relative references.
• VERSION identifies the template release. Each canonical JSON document has its own integer schemaVersion; version 1 rejects missing or unknown fields.
• Add project-specific metadata in separate project-owned documents and link them from Global context. Do not silently extend canonical JSON records.
• Emit UTC ISO 8601 timestamps with Z. The reader accepts explicit timezone offsets. History begins at createdAt and timestamps cannot go backwards.
• A compatible template update can keep record schema version 1. Incompatible record changes need a documented migration before an existing project adopts them.
• Reusable prompts stay blank until adoption. Example IDs, dates, and commands in documentation are illustrations and grant no authority.

One home for each kind of information

Canonical file	Owns	Derived or supporting files
GLOBAL/CONTEXT.md	Project identity, constraints, accepted sources	Project brief and architecture references
GLOBAL/ACCESS-MATRIX.json	Canonical selected-scope reviewed intents, denials and gaps; 20 default-deny actor/pattern prompts	XLSX review projection and optional Markdown narrative; Access Matrix grants no host permission
PLAN/MASTER-PLAN.md	Outcomes, milestones, acceptance, sequencing rationale	Task ID references
PLAN/MAP.md	Project-owned pointers to source locations, system interfaces, trust boundaries, and evidence routes	System MAP; accepted source hierarchy stays in Global context
ROOT/SX-RULES.md / ROOT/SX-MILESTONE.md (optional)	Internal coordination conventions and planning/tool-card vocabulary	ROOT planning and task delta
ROOT/PLAN.json (optional)	Request provenance and structural nodes referencing existing milestones/tasks	Derived progress; no duplicated task state
ROOT/MIRRORS.json (optional)	Actual external item bindings, timestamped observations, and bounded cards	Read-only task delta; no continuous connector
WORK/TASKS.json	Task ownership, state, dependencies, evidence, history	Six generated work views
WORK/FOCUS.json	Selected objective, existing task IDs, checkpoint pointer	Generated CURRENT.md
AGENTS/REGISTRY.json	Stable role IDs and memory paths	Each role's scoped memory
MEMORY/PROJECT.md	Verified durable facts, decisions, lessons	Dated session checkpoints
AUTOBOT/CATALOG.json	Ten fixed specialist identities/functions and Agent Alpha coordinator	Selected specialist .MD documents and AGENTA.MD
AUTOBOT/REQUESTS.json	Explicit detail request identity and retained completion evidence	Bounded context and selected freshness status
AUTOBOT/AGENDA.json	Optional Agent Alpha selected-scope settings, blank by default	Read-only session settings; no timer or scheduler
AGENTB/BOTS.json	Named BOT/DOT metadata and canonical task references	One AGENTB/.SYSTEMXB-BOT_NAME directory per instance; no provider session
DATA/.gitignore	Default local payload exclusion policy	Exact tracked README scaffolds; data audit
project.json	Explicit host-project commands	Empty config/project.example.json
INSTALLATION.json (managed installs)	Selected defaults release, version pin, profile, update policy, fingerprints	Retained defaults under .systemx/releases/<version>/

Keep raw/private runtime artifacts in ignored local storage. A role is not a running process; a report is not an authorization grant; a generated view is not a second editable ledger. Preserve original evidence when superseding it. The access matrix and map are blank Markdown records until adoption, not new canonical JSON schemas. A child .SYSTEMXP keeps its own blank copies at GLOBAL/ACCESS-MATRIX.md and PLAN/MAP.md; existing populated child files are never reset to match a newer seed. Neither document duplicates WORK/TASKS.json or WORK/FOCUS.json.

Task ledger, schema version 1

The top-level object contains exactly schemaVersion and tasks (an array). Every task contains the following fields; none are optional in stored records.

Field	Type and rule
id	Unique TASK- ID with at least three digits and a positive number; CLI allocates the next number
title	Nonempty string
owner	An ID in the agent registry
status	todo, in_progress, blocked, needs_review, done, or cancelled
milestone	Empty string or an M- ID with at least three digits declared in the master-plan table
scope	Array of nonempty strings describing intended files/systems; may be empty during intake
acceptance	Nonempty array of nonempty acceptance criteria
dependsOn	Unique IDs of existing tasks; no cycles
nextAction	String; required for in_progress, empty for terminal states
blocker	Nonempty only for blocked; empty in other states
evidence	Array of nonempty evidence references/descriptions; required for done
reviewedBy	agent.0 or user for done; otherwise empty
createdAt, updatedAt	Timezone-aware ISO timestamps
history	Nonempty chronological array of state events

Each history event contains exactly at, status, owner, note, evidence, and reviewedBy. History starts at todo; the latest event must match the task's state, owner, evidence, reviewer, and update time. Completed events retain their evidence and reviewer. Cancelled tasks need a nonempty reason in the latest note.

Current state	Allowed next states
todo	in_progress, blocked, cancelled
in_progress	todo, blocked, needs_review, cancelled
blocked	todo, in_progress, cancelled
needs_review	in_progress, blocked, done, cancelled
done or cancelled	todo

Nonterminal states also accept updates without a state change. Dependencies must be done before a task is active, under review, or complete. Reopening terminal work clears its current evidence/reviewer while preserving historical events; reopen dependent work first when necessary to keep that invariant valid.

Evidence sufficiency requires review under the evidence guide. The CLI checks metadata consistency, not identity, authenticity, or product quality.

Focus and agent records, schema version 1

WORK/FOCUS.json contains exactly schemaVersion, objective, taskIds, checkpoint, and updatedAt. Its blank state has empty strings and an empty task list. Active focus needs a nonempty objective (maximum 600 characters) and a timestamp. It can select up to ten unique existing task IDs, including completed context. A checkpoint is empty or a path to an existing Markdown file under MEMORY/sessions/; absolute paths, parent escapes, symlinks, and archive README pointers are rejected. Selection replaces the whole focus; it never changes tasks.

AGENTS/REGISTRY.json contains exactly schemaVersion and agents. Each agent has id, role, and memory. IDs are unique agent.0, agent.1, etc., without leading zeroes, plus agent.x (event-time), agent.y (cli-worker), and agent.z (review) after explicit activation with compatible tools. From 1.10.0-alpha.2, separate autobot init --apply can add agent.a (autobot-coordinator); X/Y/Z roles-init does not activate Alpha. Agent 0 must have role coordinator; other roles are nonempty descriptions. Memory must exist at AGENTS/<id>/MEMORY.md, without symlinks.

Commands and optional messages

project.json contains schemaVersion, project, checks, and commands. project contains string name and description fields. Checks are objects with unique nonempty name and nonempty command argument arrays. Commands contain exactly dev, build, and deploy; an empty array leaves an action unconfigured. See configuration and work commands.

The optional agent-message schema describes messages, with its own lifecycle. It neither replaces the task ledger nor adds a bus or scheduler. Its $id is a schema identifier; the CLI does not fetch it or contact any vendor. A general JSON Schema validator is needed to enforce that schema.

Public distribution versus adopted project

Use validate for an adopted project. Use validate --template on a pristine distribution before publication. The latter also requires:

• Reject unexpected public DATA paths before JSON/Markdown content inspection. This strict distribution inventory is separate from adopted DATA audit, which stays bounded and does not traverse payload content.
• Only the explicitly listed distribution files; no local artifacts, initialized project config, extra workers, custom documents, caches, or dependencies.
• Blank work and focus, Agent 0 only, and empty example command configuration.
• An empty project registry and blank child creation seeds; no adopted .SYSTEMXP folders.
• Reviewed blank context, plan, and memory seeds matching config/template-records.json SHA-256 values (UTF-8 text normalized to LF).
• A complete config/distribution.json inventory whose file fingerprints match the published release, including its own version and blank-record manifest.

An adopted project is expected to fail the blank-template check after it records real work. This check is not a secret scanner or an approval of every sentence; maintainers still review the source, provenance, examples, and exact export. If a blank prompt intentionally changes, review that change and update its seed hash. Do not rebaseline populated project records to make them publishable.

Publish from the reviewed tracked revision, excluding local artifacts. For a folder-only archive from this distribution repository:

git archive --format=zip --output=../SYSTEMX-template.zip HEAD .SYSTEMX

Extract the archive and run validate --template there before sharing it. The MIT license and source attribution remain part of every copy. Follow the upgrade guide when merging into an active project.

Managed installation contract, schema version 2

The optional INSTALLATION.json contains exactly schemaVersion, profile, repository, activeVersion, pinnedVersion, autoUpdate, installedAt, updatedAt, releases, and archiveDigests. Existing schema-1 state is read compatibly and converted to schema 2 on its next manager-owned state write; older releases receive a null archive receipt. Profiles are project, directory, drive, or chat. Repository is a GitHub OWNER/REPO. Version IDs are exact X.Y.Z final releases or X.Y.Z-alpha.N prereleases, with no leading zeroes and alpha N starting at 1. The selected ID determines the discovery channel; see release policy. pinnedVersion is either null or the active version. In the 1.8.9 and later check-only managers, a pinned version may use either autoUpdate: "manual" or the opt-in "on-start" release notice. The notice never selects a release. Older root managers may retain automatic startup selection until explicitly refreshed. releases maps retained version IDs to their distribution-manifest SHA-256 values. archiveDigests maps the same IDs to null or a receipt with sha256 and verifiedBy (explicit-pin or observed-only). A receipt is not a publisher signature.

An update appends a verified default snapshot and creates missing root files. It never replaces or deletes an existing project file, folder, or release snapshot. Only manager-owned selection/check metadata changes, with earlier selection states retained. Root VERSION and copied default files therefore retain their initial contents; the selected defaults version comes from INSTALLATION.json. Running a selected release must use the outer project's mutable records. Snapshot records are blank seeds and never become the active project's ledger or memory.

The distribution manifest contains exactly schemaVersion, version, and files, mapping portable relative file paths to SHA-256 fingerprints normalized to LF. It excludes its own fingerprint. Immutable release snapshots include the manifest itself; installation state records that manifest's fingerprint. Fingerprints detect changed artifacts relative to the selected source; they are not independent publisher signatures. See installation for policy, local locking, interrupted writes, and filesystem limits.

SYSTEMX PROJECTS, schema version 1

Projects/REGISTRY.json contains exactly schemaVersion: 1 and projects. Each entry has exactly name, path, records, and kind. Paths are relative to the outer .SYSTEMX and must equal Projects/NAME and Projects/NAME/.SYSTEMXP. Names are unique ignoring case; use the exact stored spelling for selection. The public registry is empty.

A child's ledger, focus, agent registry, and project.json use the contracts below, scoped to that child. project.name must match its registry name. SOURCES.json contains schemaVersion: 1 and sources; each source has kind, location, and description. See SYSTEMX PROJECTS for allowed kinds, path rules, local status snapshots, and command examples.

IDs and dependency edges stay inside one ledger. Qualified project/task references are prose coordination links, not cross-ledger dependencies. Each child has its own Agent 0 memory but shares the outer defaults, pin, and update policy. There are no nested .SYSTEMX installs, implicit current project, automatic source transport, or recursive child workspaces. Unknown custom registries need reviewed migration; the tools reject them without replacing their files.

Agent X, Agent Y, and Agent Z records

This section includes the 1.9.0-alpha.2 Agent Y extension. In the older 1.8.9-alpha.1 release, roles-init --apply activates X/Z only and has no Agent Y job ledger.

The public registry remains Agent 0 only. roles-init --apply explicitly adds standard role entries and project-owned records while preserving existing bytes. Activated agent.x/agent.y/agent.z IDs require tools that support them; older readers are not compatible with those added IDs. Record schema version 1 is otherwise unchanged. A downgrade after activation requires a reviewed migration or backup.

EVENTS/EVENTS.json contains schemaVersion: 1 and events. Each event has id, key, at, recordedAt, actor (kind, id), kind, stage, summary, tasks, revision, and evidence. Stable-key replays preserve the original record and conflicting facts are refused. EVENTS/SCHEDULE.json contains schemaVersion: 1 and items, with one due occurrence per item and explicit open/complete/cancelled bookkeeping. See Agent X.

AGENTS/agent.y/JOBS.json is a scoped, portable Agent Y handoff ledger created only after role activation, with top-level schemaVersion: 1 and jobs. Each job refers to one existing agent.y-owned task, one selected provider, a repository identity and observed base revision, allowed file scope, execution result, and optional owned GitHub branch/PR lifecycle. It records identities, revisions, and evidence references rather than raw prompts, full transcripts, absolute host paths, or configured adapter arguments. An ignored, owner-only state/agent-y/Y-<id>.json sidecar in the selected scope holds local repo, prompt, and worktree paths plus configured arguments. Do not publish or sync that host-local state; a portable job alone cannot resume execution on a different machine. A whole-folder copy may include ignored files, so inspect backup scope. The job does not replace task status, authenticate the provider, or install its CLI. A draft PR is opt-in after a successful run; ready, abandoned close, and verified cleanup after merged/accepted state are separately gated. Cancelled unmerged work is retained. Agent Y has no merge command. See Agent Y for commands and authority boundaries.

REVIEWS/POLICY.json contains schemaVersion: 1, policyId, version, and exactly ten categories, each with id, name, and exactly ten questions (id, question). Stable IDs are C01–C10 and Z01.01–Z10.10. A question change requires a new policy version; used policy versions are frozen under policies/. Requests retain the subject, code/input revision, evidence revision, stage, policy snapshot/hash, and all 100 answers. Reports preserve answers, derived scores, source fingerprints, and time. See Agent Z for the answer contract, scoring, comparison, and immutable-report behavior.

Normal validation checks current optional event/schedule ledgers, Agent Y jobs, and review policy when present. Historical review requests/reports have explicit selected-ID validation; they are not all loaded into context. None of these records replaces WORK/TASKS.json, authenticates a worker, or proves evidence independently.

Tier 2 AUTOBOT records, schema version 1

The generic public panel retains ten exact named specialists plus AGENTA.MD. Its registry remains Agent 0 only until explicit adoption. autobot init --apply adds agent.a (autobot-coordinator) and missing selected-scope records without replacing existing bytes. This is separate from X/Y/Z roles-init; no role activation starts a process or expands authority. AUTOBOT manual.

AUTOBOT/CATALOG.json contains exactly schemaVersion, coordinator, maximum, and bots. Coordinator is agent.a, maximum is integer 10, and the ordered list retains exactly ten stable slots: autobot.design, autobot.soul, autobot.memory, autobot.rules, autobot.research, autobot.brand, autobot.media, autobot.tokens, autobot.data, and autobot.archive. Each slot contains id, name, file, and a bounded nonempty functions array. IDs, names, exact-case AUTOBOT/Design.MD through Archive.MD paths, and slot order are fixed; adopted project functions/detail can change within the reviewed schema.

AUTOBOT/REQUESTS.json contains exactly schemaVersion and requests. Each request has id, createdAt, identity, state, and completion. Identity contains selected scope, caller, purpose, external input revision label, optional existing task ID, selected sorted specialist IDs, catalog policy hash, and the charter/selected-file path/hash/byte inventory. ID is ABR- plus 20 hexadecimal characters from that identity's fingerprint. State is requested or complete. A requested record has null completion; completion has completedAt, summary, responseRevision, and nonempty original evidence references. Time is strict, chronological, and future timestamps beyond the small host-clock tolerance are refused. Completion and detail do not modify canonical task status.

Each selected document is bounded at 256 KiB; context at 64 KiB; request history at 4,096 entries and 8 MiB. Source paths are contained, exact-case, unlinked files. A repeated identity reuses a completed result without refreshing its evidence time. Source/catalog changes make a historical result stale and refuse completion against old context. A declared external input revision is not fetched or independently checked. Selected status inspects current document fingerprints; summary status does not scan all historical results. These are consistency checks and caller claims, not authentication or independent proof.

Optional child panel initialization uses the same schema under its .SYSTEMXP; no root/sibling facts or requests are inherited. Ordinary default updates are additive. Context does not preload the panel or recursively read DATA.

Local DATA scaffold contract

DATA/.gitignore ignores payloads by default while allowing only its own policy, root README, eight exact standard directories, and each directory's direct README. The directories are TEMP, LARGE, IMPORTS, RESEARCH, ASSETS, EXPORTS, CACHE, and ARCHIVE. Each re-ignores contents, so arbitrary nested READMEs remain ignored. A child has a separate optional DATA tree. data init --apply adds missing seed files only; status/audit are bounded synthetic-ignore-probe and tracked-index reports, not exhaustive verification of actual untracked paths. A custom per-file exception can evade the probes; check named exports with git check-ignore. Git policy is unverified without a repository/Git. Already tracked/history/force-added files are not made private by ignore. There is no automatic transport, upload, recursive payload scan, untracking, or deletion. Full DATA manual.