Getting Started Easy Mode

Getting Started Easy Mode

Start with one project, one outcome, and Agent 0. .SYSTEMX gives your human and AI sessions a shared place for the plan, tasks, evidence, and next step. Your chosen Codex, VS Code, other IDE, or CLI supplies the actual assistant and tools.

Shortest route: choose your project → copy the reviewed folder if absent → record one outcome → paste the setup prompt in step 3. The command tools in step 4 are optional.

Baseline: .SYSTEMX 1.11.0-beta.4 / Python package 1.11.0b4. Watch the current 4K introduction or open the all-in-one Synergy Map to see how the parts connect. The full Getting Started guide covers additional profiles.

This is beta software. Review the selected release and keep a recoverable copy of important work. See the release policy.

1. Choose the project you actually want to work on

Open that project's containing directory in your editor or file manager. The resulting layout is:

your-project/
├── your existing code and documents
└── .SYSTEMX/

Use the exact name .SYSTEMX, including the leading dot and uppercase letters. Inspect hidden files first. If the project already contains it, continue its records instead of copying over them; follow Installation and Updates for a managed upgrade. Do not put a second .SYSTEMX inside the first one.

For a first project, use the outer .SYSTEMX scope. Named Projects/NAME/.SYSTEMXP children are optional and must be selected explicitly. See multiple projects when you need them.

2. Start with the documents — no terminal required

1. Review the beta.4 release and its tagged source. Download and extract the reviewed release/source archive.
2. If your project has no .SYSTEMX, copy the complete .SYSTEMX folder from that clean distribution into your project. Include hidden files. Use a clean release, since an adopted project's folder can contain private ignored data that ordinary copying would carry with it.
3. Open .SYSTEMX/START-HERE.md, .SYSTEMX/AGENTS.md, and .SYSTEMX/STANDARD.md.
4. Record only known facts in .SYSTEMX/GLOBAL/CONTEXT.md: what the project does, who it is for, its constraints, and the sources you trust.
5. Put one outcome and how you will recognize success in .SYSTEMX/PLAN/MASTER-PLAN.md. Keep unknowns visible.

Reading and editing these documents requires no Python installation. Copying the folder does not install the managed CLI or activate an assistant. The optional CLI path below adds managed version selection and record commands.

Adopt this in your own project. The public template's project records stay blank for the next person.

3. Give your assistant one clear setup request

Open your selected project in Codex, VS Code, or your chosen harness, then paste this after replacing the two bracketed lines:

Set up or resume .SYSTEMX for this selected project.

Project directory: [the containing directory I have opened]
First outcome: [one concrete result and how I will check it]

Read the applicable host/repository instructions, then .SYSTEMX/AGENTS.md,
.SYSTEMX/START-HERE.md, and .SYSTEMX/STANDARD.md. Inspect existing files and
local changes. Use the outer root scope unless I explicitly name a registered
child project.

Preserve existing work. Record only observed project facts and explicit
requirements. Keep unknowns visible. Use Agent 0 to coordinate one bounded
task in the canonical task ledger, with its acceptance criteria, scope and
next action. Use the task commands when available; if they are unavailable,
prepare the proposed task details and identify the required setup step.

Use only the tools and access authorized in this session. Do not put secret
values into messages, shared records or examples. Add other roles or provider
connections only when the selected work requires them.

After doing the authorized work, report the actual evidence and remaining
gaps, and save a precise checkpoint with the next action.

Some tools discover a root AGENTS.md automatically; others need the explicit file reference above. The optional onboard bridge command previews a short root pointer. Existing root instructions require review rather than replacement. See provider and harness onboarding.

4. Optional: install the managed command tools

Show optional macOS/Linux and Windows CLI setup

Use this path when you want first-run, version pinning, task commands, and format checks. Commands require Python 3.9+. The Git-based package install also requires Git. Install those through their normal trusted installers if needed.

The following examples use a dedicated tool environment outside the project. If that environment already exists, inspect its selected version before reusing or changing it. Reading the guide does not require installing anything.

macOS / Linux

Create the tool environment and install the selected release:

python3 -m venv "$HOME/.venvs/dotsystemx"
"$HOME/.venvs/dotsystemx/bin/python" -m pip install \
  "git+https://github.com/WayneTechLab/dotSYSTEMX.git@v1.11.0-beta.4"
systemx() { "$HOME/.venvs/dotsystemx/bin/python" -I -B -m systemx "$@"; }
systemx --version

Change into your actual project directory, then preview:

cd "/path/to/your-project"
systemx first-run --target "$PWD" --profile project --version 1.11.0-beta.4

Read the proposed target, selected version, preserved files, and remaining steps. When they match your intended project, apply that same selection:

systemx first-run --target "$PWD" --profile project --version 1.11.0-beta.4 --apply
systemx status --target "$PWD"
systemx run --target "$PWD" --offline -- validate
systemx run --target "$PWD" --offline -- doctor
systemx run --target "$PWD" --offline -- context --agent agent.0
systemx run --target "$PWD" --offline -- onboard plan

Windows PowerShell

Create the tool environment and install the selected release:

py -3 -m venv "$HOME\.venvs\dotsystemx"
& "$HOME\.venvs\dotsystemx\Scripts\python.exe" -m pip install "git+https://github.com/WayneTechLab/dotSYSTEMX.git@v1.11.0-beta.4"
function systemx { & "$HOME\.venvs\dotsystemx\Scripts\python.exe" -I -B -m systemx @args }
systemx --version

Set the actual containing project directory, then preview:

$projectRoot = "C:\Projects\YourProject"
systemx first-run --target $projectRoot --profile project --version 1.11.0-beta.4

After reviewing the preview, apply the same selection and read it back:

systemx first-run --target $projectRoot --profile project --version 1.11.0-beta.4 --apply
systemx status --target $projectRoot
systemx run --target $projectRoot --offline -- validate
systemx run --target $projectRoot --offline -- doctor
systemx run --target $projectRoot --offline -- context --agent agent.0
systemx run --target $projectRoot --offline -- onboard plan

Calling the environment's Python directly avoids changing global PATH or PowerShell activation policy. Define the systemx function again in a new shell.

These examples select the exact release without an independent archive digest. For that additional verification, obtain the digest of the exact codeload tag ZIP through a separately trusted record and add --archive-sha256 with its 64-hex value to the first-run preview and apply commands. A wheel or other release ZIP checksum is not interchangeable. See Installation and Updates.

First run preserves existing project files, adds missing defaults, creates empty command configuration only when absent, and pins a new installation with manual updates. A conflicting executable or separate case variant requires review. An already managed project keeps its existing selected version and policy; first-run does not upgrade it.

validate checks record consistency. doctor checks local prerequisites and configured command names. Neither proves that your app works or that an external account is authenticated. --offline skips the manager's optional startup update check for that invocation; it does not restrict other tools' network access.

5. Finish one small task and leave a useful checkpoint

In an adopted project, have Agent 0:

1. Capture the outcome and its observable acceptance criteria.
2. Create one task through task-add and keep the returned TASK- ID.
3. Select that ID with focus, then start the authorized work.
4. Retain the actual commands, source revision, result and evidence.
5. Move the task to needs_review; Agent 0 or the owner accepts done only after reviewing evidence.
6. Save verified facts, unresolved gaps and the exact next action in the selected scope's memory/checkpoint records.

For example, this creates and focuses a task in your adopted root scope:

systemx run --target "/path/to/your-project" --offline -- task-add \
  --title "Record this project's purpose and first outcome" \
  --owner agent.0 \
  --acceptance "The owner can verify the purpose, constraints and first outcome against the project" \
  --scope "GLOBAL/CONTEXT.md" --scope "PLAN/MASTER-PLAN.md" \
  --next "Inspect the existing project and record only known facts"

Copy the returned ID; replace TASK_ID_FROM_OUTPUT below. This works in PowerShell too when entered as one line with your real target:

systemx run --target "/path/to/your-project" --offline -- focus \
  --objective "Establish this project's first accepted outcome" \
  --task TASK_ID_FROM_OUTPUT

Task mutations do not use --apply; they write canonical records immediately. Use your real project details. This example does not perform the task or claim acceptance. The Task Workflow explains the full lifecycle.

Your first checkpoint is useful when another session can identify the selected project, current outcome, task ID, original evidence, remaining gap and next action. Empty task lists and passing template validation do not establish that the project is complete.

Add capabilities only as they become useful

You need…	Go here	First look
Agent 0 and available role/instance records	Agent 0 Roster	root roster
Events, a selected external CLI, or a fixed review	Agent X, Agent Y, Agent Z	Preview roles-init; apply only when needed
Design, brand, research or other selected references	AUTOBOT and Agent Alpha	autobot list; preview autobot init
Named BOT/DOT workspaces	Agent Beta, Agent1 and Agenda	Preview agent-beta setup
Advisory security and credential setup	Agent Beta, Agent1 and Agenda	agent-1 setup, agent-1 check
Settings and access review	Access Matrix	agenda catalog, agenda status
Codex / SDK / IDE or other provider navigation	Provider and Harness Onboarding	onboard plan
Host-owned structured reads	Agent 0 Toolchain I/O	service status
Several explicitly selected projects	SYSTEMX Projects	projects list
Private or large payloads	Local DATA Storage	data audit
Version updates or removal/recovery	Installation and Updates, Uninstall and Cleanup	Inspect the target and preview the operation

The table contains folder CLI suffixes. In a managed installation, prefix them with systemx run --target PROJECT --offline --. In a trusted folder-only copy, run them from its containing project with bash .SYSTEMX/SYSTEMX.sh COMMAND or pwsh -File .SYSTEMX/SYSTEMX.ps1 COMMAND. Managed run requires a managed installation; it does not execute an unmanaged folder automatically.

A role record does not start a worker. Provider login and actual OS/GitHub/cloud permissions remain separate. Keep credential values out of shared files and assistant messages. GitHub Actions secrets serve Actions workflows and cannot be linked back into a local .env; choose the actual local consumer separately. Agent1 findings are advisory, and its local check does not certify a device as clean. Native Windows has additional file-backed Agent1 limits described in the linked setup guide.

Continue with the Daily Workflow, full Getting Started guide, or the complete Synergy Map.