Getting Started

Getting started

This guide takes you from a clean copy of .SYSTEMX to an initialized project with shared context and a clear next task.

1. Choose how to adopt it

For a new repository: select Use this template, create your repository, and clone it locally.

For an existing repository: copy the complete .SYSTEMX folder into the project root. Preserve its license. If a .SYSTEMX folder already exists, compare and merge its files instead of overwriting configuration or project history. The source template's wiki is reference documentation; the copied folder contains its own local instructions. Copy from a clean checkout or reviewed archive: copying a working project's folder can include ignored private data. See Upgrading for existing layouts.

2. Check the prerequisites

Use	Requirement
Read and edit project documents	A Markdown editor or assistant with file access
Run the CLI	Python 3.9+; no third-party Python packages
Use the shell launchers	Bash on macOS, Linux, WSL, or Git Bash
Use native Windows Python	py -3 .SYSTEMX/scripts/systemx.py followed by the command
Run project checks or builds	The runtimes and tools selected by that project

Git is useful for versioning and synchronization. doctor reports Git state when Git is available, but it does not contact remote services.

3. Inspect the clean template

Run these commands from the repository root:

bash .SYSTEMX/SYSTEMX.sh validate
bash .SYSTEMX/SYSTEMX.sh validate --template
bash .SYSTEMX/SYSTEMX.sh doctor
bash .SYSTEMX/SYSTEMX.sh status

Expect template validation to pass, no initialized project command config, and zero recorded tasks. An empty task list means no work has been recorded; it does not establish project completion. The additional --template check is only for a pristine distribution. Once the project has real records or configuration, use ordinary validate.

4. Initialize project commands

bash .SYSTEMX/SYSTEMX.sh init

This creates .SYSTEMX/project.json from the empty example. It refuses to overwrite an existing config. Edit the file to provide your project name and real command arrays. See Configuration and quality.

The task and memory workflow can be used before command initialization. Running check, build, or deploy requires the corresponding configuration.

5. Establish project context

Fill these records with facts about the adopted project:

• GLOBAL/CONTEXT.md: purpose, constraints, sources, and shared expectations.
• PLAN/MASTER-PLAN.md: outcomes, milestone IDs, dependencies, and acceptance.
• MEMORY/PROJECT.md: verified facts, decisions, lessons, and continuity references.
• AGENTS/agent.0/MEMORY.md: the coordinator's current mission and next action.

All paths above are inside .SYSTEMX. Copy the project-brief and architecture templates into .SYSTEMX/project/ when needed. Leave reusable templates blank. Create the first concrete tasks using the task workflow. Select the objective and existing task IDs with focus; its generated CURRENT.md becomes the current resume pointer.

6. Connect your assistant

Start each session with .SYSTEMX/START-HERE.md, then load:

bash .SYSTEMX/SYSTEMX.sh context --agent agent.0

Merge the guidance in .SYSTEMX/templates/AGENT-ENTRYPOINT.md into your existing root AGENTS.md or your tool's equivalent discovery file. Do not replace repository instructions. Tools differ in which files they automatically read; the hidden folder alone does not guarantee automatic discovery.

Adoption complete

You are ready to begin project work when the shared context is recorded, the next task has a clear owner and acceptance criteria, and the selected tools are available. Treat release readiness as a separate decision supported by the project's checks and operations process.