Command Reference

Command reference

Run commands from the project directory containing .SYSTEMX, or invoke its launcher using an absolute path. Root project commands execute from the outer containing project directory. Selected child commands execute from .SYSTEMX/Projects/NAME, beside .SYSTEMXP.

bash .SYSTEMX/SYSTEMX.sh --help

Direct project role commands use the local launcher, for example bash .SYSTEMX/SYSTEMX.sh agent-beta status from the containing project root. On Windows PowerShell, use pwsh -File .SYSTEMX/SYSTEMX.ps1 agent-beta status. The installed systemx package CLI manages versioned installation and routes project commands only through run --target PATH --offline -- COMMAND or explicit projects --target PATH -- COMMAND; systemx agent-beta is not a direct package command.

The compatibility launcher .SYSTEMX/WSG-MENU.sh accepts the same arguments. On native Windows, use .SYSTEMX\SYSTEMX.ps1 with the same command and flags. For a managed installation, the package command systemx run --target ... -- <command> selects the intended release even when an older root launcher is retained. The direct systemx projects --target ... -- <subcommand> routes explicit child operations through the selected outer release. See CLI and Tools for the entry-point and project-tool distinctions. A reviewed unmanaged local folder copy can use its own shell/PowerShell launcher; external manager execution still requires a valid managed installation.

Installation and version management

Read release policy before upgrading an older manager to beta. The tool version and each project's selected defaults version are independent. The current installation version is 1.11.0-beta.4. The older v1.9.0-alpha.1 was withdrawn and must not be installed. Review the current beta prerelease and its independently verified codeload ZIP digest before remote installation.

These commands belong to the systemx package CLI, also available through python3 -I -B .SYSTEMX/manager.py. All targets are explicit local project roots. The direct manager, runner, and release scripts enter Python isolated mode before imports. When calling them directly, include -I as shown in the examples; the script entry points also enforce that boundary. The installed systemx console command resolves its package first, then restarts isolated before manager import; use a reviewed virtual environment's Python with -I -B -m systemx for isolation from the initial import.

Command	Behavior
--version	Report external tool version, channel, and Python package spelling; no target required
first-run --target PATH	Preview installation/adoption and empty config initialization
first-run --target PATH --apply	Apply first-run setup without running project commands; preserve existing files/settings
audit --target PATH	Offline inspection of the selected folder, case variants, and operation receipts
uninstall --target PATH --backup NEW_PATH	Preview archiving the whole folder, including user records, outside the project
uninstall --target PATH --backup NEW_PATH --apply	Archive, verify, remove the local alias if present, and write an external log
restore --target PATH --backup PATH	Verify a removal backup and preview restoration
restore --target PATH --backup PATH --apply	Restore a verified backup only into an empty destination
setup --profile project	Print a profile's setup URL and persistence model; also directory, drive, or chat
install --target PATH --profile project	Install bundled defaults, append missing files, and pin the version
install --target PATH --version 1.11.0-beta.4	Install the exact GitHub release
install --target PATH --source PATH	Install from a reviewed local distribution without downloading
update --target PATH --version 1.11.0-beta.4	Select the exact release after unlocking; preserve existing project files
install, update, or first-run with --version VERSION --archive-sha256 DIGEST	Pin the exact remote codeload ZIP digest before parsing; obtain it independently
bootstrap-refresh --target PATH --source /reviewed/new/.SYSTEMX	Preview additions, replacements, and conflicts for eight stock root bootstrap and launcher files
bootstrap-refresh --target PATH --source /reviewed/new/.SYSTEMX --apply	Add historically absent stock files and back up/replace recognized stock files; refuse customized or unrecognized files
install or update with --dry-run	Print additions, preserved paths, and conflicts without writing the target
install --target PATH --lowercase-alias	Opt in to a local relative lowercase link; case-insensitive paths need no link
alias --target PATH	Inspect exact stored casing and alias without writing or contacting the network
alias --target PATH --create	Create the local link if needed; --dry-run previews without changing files
policy --target PATH --pin none	Explicitly unlock the selected version
policy --target PATH --pin current	Lock the current selection and reset startup checks to manual
policy --target PATH --auto on-start	With a refreshed 1.11.0-beta.4 check-only root manager, report available releases at startup, even while pinned; never select one automatically
policy --target PATH --auto manual	Disable startup checks without changing the version selection or pin
status --target PATH	Verify and show defaults version, derived channel, pin, profile, selected archive digest receipt, and retained versions; no network
run --target PATH --offline -- status	Run project task status using installed defaults without a network check
projects --target PATH -- list	List registered child scopes using selected outer defaults; offline by default
projects --target PATH -- context --project NAME	Read explicit child context; target is the directory containing outer .SYSTEMX
projects --target PATH --online -- status --project NAME	Permit an eligible check-only startup notice, then read the selected child; no automatic selection
export-chat --target PATH --output NEW_FILE	Write a new local chat packet; no upload or overwrite

Manager status describes the installation. Project run ... -- status describes the task ledger. New installs are pinned and manual. Omitting the version on an unpinned update uses the current selection's channel: final-version projects discover final releases; beta projects can discover published beta and final releases according to the release policy. Read Installation and updates for retention, startup timing, major-version boundaries, and recovery. A dry run can download and verify a requested release, but it makes no target changes. The check-only on-start policy reads release metadata and prints a notice; it does not download or select the discovered archive. New selections require a separate explicit update, ideally with --version and an independently obtained --archive-sha256. The older preserved root manager can retain its prior startup-selection behavior; refresh it before enabling check-only notices. --archive-sha256 requires an exact remote --version and cannot be used with --source or unversioned discovery. See the independent archive pin for the digest's exact byte stream and trust boundary.

Run bootstrap-refresh from the reviewed new tool, such as a separate checkout or newly installed package, before update when it reports that the root bootstrap differs. The command previews add, replace, and conflicts by default. It checks manager.py, lifecycle.py, versions.py, systemx_paths.py, SYSTEMX.sh, SYSTEMX.ps1, INSTALL.sh, and INSTALL.ps1 against the new distribution and every intact retained release; customized or unrecognized files block the operation. A missing file is added only if no intact retained release ever contained it, such as versions.py in a genuine historical v1.5.0 install. A file that was present in a retained release but is missing now is a conflict. --apply saves byte-for-byte copies of replaced files under .SYSTEMX/.systemx/history/ and records an operation log. An add-only refresh has no original file to back up. The target must already be a managed installation. With a remote source, provide an exact --version; --archive-sha256 can independently pin that ZIP. Refreshed managed shell and PowerShell launchers invoke Python with -I -B. When invoking a reviewed external manager directly, use python3 -I -B /reviewed/new/.SYSTEMX/manager.py. First installation or adoption also rejects conflicting preexisting .py, .sh, and .ps1 defaults instead of treating them as trusted stock code. This manager installs and newly selects only releases 1.8.7-alpha.1 or newer. It can run an already selected, verified older snapshot through an isolated compatibility shim; its code and record behavior remain historical. Recovering an earlier release for selection requires a separately reviewed backup or legacy path, not a bootstrap-refresh rollback.

Removal and restore require the external library or a separate reviewed checkout, not a manager or current directory inside the folder being moved. The backup must be a new external path on the same filesystem. Preview makes no target changes; --apply is explicit. See first-time setup and uninstall, logs, and cleanup scope.

Inspection and setup

Command	Behavior
No arguments or menu	Open the interactive menu; EOF exits.
help or --help	Print command usage.
validate	Check template files, JSON/config structure, local Markdown file links, coordination records, and generated work views.
validate --template	Also require reviewed blank records and only distribution files; inspect normally ignored folders for extras.
doctor	Report paths, Python version, available Git state, configuration, and executable availability.
paths or alias	Inspect canonical casing and lowercase path behavior; menu option 11
alias --create	Enable the local lowercase link; menu option 12
setup-guide	Print the first-time guide; menu option 13
removal-guide	Print uninstall/restore instructions; menu option 14
Menu option 15	Print the SYSTEMX PROJECTS guide
Menu option 16	List registered projects
Menu option 17	Print Agent X/Y/Z guides in 1.11.0-beta.4
tools-guide or menu option 18	Print the local CLI and Tools guide; no provider install, launch, or configuration
Menu 19–21	Agent Alpha/AUTOBOT, local DATA, and ROOT guides
Menu 22–23	Agent Beta status and setup preview
Menu 24–26	Agent1 setup status, first-run question preview, and All-In-One advisory check
Menu 27–28	Agenda/Access Matrix status and table
Menu 29–30	Local session service status and update/release guide
Menu 31–32	Scoped session settings/Rules hashes and public GitHub release/deployment counters
Menu 33	Read-only outer-scope Agent 0 roster
Menu 34–36	Onboarding status, first-time plan, and project-root instruction bridge preview
Menu 37	Read-only installed Agent Y CLI names; no authentication probe
Menu 38	Read-only Agenda settings and access decision-rule catalog
init	Create .SYSTEMX/project.json; refuse to overwrite it.
status	Print recorded task counts, open work, and registered role IDs.
context --agent agent.0	Load current focus, shared context, master plan, project memory, selected agent notes, and relevant open-task summaries.
refresh-work	Regenerate six work views and CURRENT.md from valid canonical records.
task-ready	List TODO tasks with completed dependencies; optional --agent filters the registered owner.

doctor itself does not contact services or prove authentication. An opted-in managed launcher may check for updates before running it; use run --offline to prevent that startup check. validate does not check external URLs, heading anchors, application behavior, or the truth of recorded evidence. context defaults to agent.0 and labels truncated output. Use --template only for a pristine distribution. Real project records are expected to fail that extra check after adoption; use ordinary validate then.

Use exact .SYSTEMX paths in every command and prompt. Conflicting case variants stop execution before project writes. The case and alias guide explains safe recovery, old launchers, and the distinct internal version cache.

Select current focus

bash .SYSTEMX/SYSTEMX.sh focus --objective 'Finish the accepted outcome' --task TASK-001

--objective is required unless using --clear and allows up to 600 characters. Repeat --task for up to ten unique existing IDs. --checkpoint optionally names an existing Markdown file under MEMORY/sessions/, relative to .SYSTEMX. The command replaces the complete selection, so repeat every ID to retain. focus --clear accepts no selection fields and preserves tasks and checkpoints.

Current task status, next actions, and blockers are always read from the ledger. The focus timestamp records the selection, not a fresh runtime observation.

Prepare a worker packet

# Supply the source revision you have just observed.
bash .SYSTEMX/SYSTEMX.sh task-packet TASK-001 --base 'REPLACE_WITH_VERIFIED_REVISION'

Both the existing task ID and --base are required. The caller-supplied revision is recorded as context; this command does not verify it. The packet includes the task scope/acceptance, dependency summaries, and selected owner's memory, capped at 14,000 and 3,000 characters respectively with explicit truncation notices.

task-ready and task-packet are read-only and do not dispatch agents. Dependency readiness alone does not establish write-scope, resource, or permission readiness. A packet may describe blocked work for diagnosis; inspect the actual task state before dispatch. Use task-show for original dependency evidence and full detail.

Project commands

Command	Execution order
check	Template validation, then configured checks in order
dev	Template validation, then the configured development command
build	Template validation, configured checks, then build
deploy	Template validation, configured checks, build, then deployment

Each supports --dry-run, which prints the plan without running project commands. Required empty configuration fails. Before executing a plan, the runner checks executable availability for every step; a failed executed command stops the sequence. Configure scripts carefully: the runner does not choose an environment, authenticate, commit, push, or perform a live smoke check.

Register a worker

bash .SYSTEMX/SYSTEMX.sh agent-add agent.1 --role test

The worker ID must use agent. followed by a positive integer. agent.0 is the existing coordinator. Registration creates a memory file and registry entry, without starting an agent process or overwriting an existing worker.

Create a task

bash .SYSTEMX/SYSTEMX.sh task-add --title 'Task title' --acceptance 'Acceptance criterion'

Flag	Required?	Meaning
--title	Yes	Nonempty task title
--acceptance	Yes; repeatable	Acceptance criteria
--owner	No	Registered owner; defaults to agent.0
--scope	No; repeatable	Intended files or systems in scope
--depends-on	No; repeatable	Existing prerequisite task IDs
--milestone	No	ID declared in the master-plan table
--next	No	Concrete next action

New tasks start at todo and receive the next TASK-001-style ID.

Inspect or update a task

bash .SYSTEMX/SYSTEMX.sh task-show TASK-001
bash .SYSTEMX/SYSTEMX.sh task-set TASK-001 --status in_progress --next 'Concrete next action'

task-set flag	Meaning
--status	One of todo, in_progress, blocked, needs_review, done, cancelled
--owner	Reassign to a registered role
--next	Set the next action; required to be nonempty for in_progress
--blocker	Explain what prevents progress; required for blocked
--evidence	Append an evidence reference; repeat for multiple entries
--reviewer	Record agent.0 or user when accepting done
--note	Add a history note; required when cancelling work

At least one change or note is required. Transition and dependency rules apply; see Task workflow. Completed or cancelled tasks reopen to todo before further editing.

Exit behavior

• 0: the requested operation succeeded within its documented scope.
• 2: usage, configuration, record-validation, or handled file errors.
• A failed project command's positive exit status is returned by the runner.
• An interrupted CLI returns 130.

The interactive menu reports an action's failure and returns to the menu. For automation that needs a reliable action exit status, invoke the command directly.

SYSTEMX PROJECTS

Run from the outer workspace root, or pass the same arguments through systemx run --target WORKSPACE -- projects ...:

bash .SYSTEMX/SYSTEMX.sh projects list
bash .SYSTEMX/SYSTEMX.sh projects add Project-A --kind software
bash .SYSTEMX/SYSTEMX.sh projects add Project-A --kind software --apply
bash .SYSTEMX/SYSTEMX.sh projects context --project Project-A --agent agent.0
bash .SYSTEMX/SYSTEMX.sh projects status --root
bash .SYSTEMX/SYSTEMX.sh projects refresh-status --project Project-A --apply
bash .SYSTEMX/SYSTEMX.sh projects validate --project Project-A
bash .SYSTEMX/SYSTEMX.sh projects validate
bash .SYSTEMX/SYSTEMX.sh projects check --project Project-A --dry-run
systemx export-chat --target WORKSPACE --project Project-A --output NEW_PACKET.md

task-add, task-set, task-show, task-ready, task-packet, focus, agent-add, and refresh-work accept their existing flags with --project NAME or --root under projects. Execution commands are check, dev, build, and deploy, with --dry-run available. Creation kinds are general, software, research, operations, and channel. validate without a selector explicitly checks every registered scope. No implicit project, source fetch, or agent launch occurs. See SYSTEMX PROJECTS for the complete contract.

Direct installed CLI for child scopes

From alpha.5, the external CLI accepts:

systemx projects --target "/path/to/workspace" -- list
systemx projects --target "/path/to/workspace" -- context --project Project-A
systemx projects --target "/path/to/workspace" -- roles-init --project Project-A
systemx projects --target "/path/to/workspace" -- agent-y providers --project Project-A
systemx projects --target "/path/to/workspace" -- check --project Project-A --dry-run

The outer command defaults to --offline. --online permits an eligible configured startup release check; it does not download/select defaults or sync cloud records. --offline suppresses only startup discovery, not network use by explicitly invoked project commands, providers, Git, or gh. Arguments after -- belong to the selected release's projects interface. Scope is always --project NAME or --root for scoped operations; listing and deliberately all-scope validation have their documented exceptions. The existing systemx run --target PATH --offline -- projects ... wrapper remains available. projects executes no command merely because a source URL, provider, or child record exists. See SYSTEMX PROJECTS.

Beta role, security, Agenda, and context commands

These commands use the selected root or an explicit projects ... --project NAME child. Preview mutating operations, inspect the selected scope/revision, then apply only the reviewed action. Agent Beta, Agent1, and Agenda has the exact boundaries.

Local command family	Use
agent-beta setup / bot-add BOT_NAME --kind bot / access-link BOT_NAME	Preview/apply offline named BOT/DOT records and an existing reviewed decision reference
agent-1 setup / status / questions / check --profile all-in-one	Guided first-run metadata and warning-only review; 20 categories of 20 questions
agent-1 env-inventory / env-sanitize / env-migrate	Names-only dotenv review, sanitized example preview, and explicit hidden-input GitHub Actions secret path
onboard status [--provider ID] [--surface SURFACE]	Read-only selected-scope Agent1/roster/provider navigation; installed-name result does not authenticate
onboard plan [--account-context personal|enterprise] [--credential-consumer CONSUMER]	Read-only first-time questions and credential-consumer boundary; optional --env-file requests Agent1 names-only review on supported hosts
onboard bridge [--apply --expected-sha256 SHA]	Preview or exclusively create a fixed root AGENTS.md pointer to .SYSTEMX/AGENTS.md; preserve an existing file
agenda init / catalog / status / table / decision-add	Fixed setting and decision-rule catalog, selected-scope state, and reviewed decision preview/apply
agenda workbook-export / workbook-check / roles-upgrade	Formula-free XLSX projection, drift check, and reviewed stock-row adoption
session-settings [--compact]	Selected-scope role/status and Rules summary; full mode includes per-file hashes, compact mode an aggregate revision
service status / service start --stdio	Capability report or explicitly started read-only JSON-lines session; no daemon
python3 -I -B .SYSTEMX/scripts/release_counters.py	Read-only GitHub release and deployment observation; unknown stays unknown

On macOS/Linux, Agent1 dotenv and answer-file operations use anchored no-follow handles with a one-megabyte post-open bound. Existing setup reconfiguration requires a full eight-answer preview and --apply --replace-existing --expect-sha256. Windows fails closed for those file operations and setup reconfiguration; metadata first-run setup/status/questions and advisory filename scan remain. See the exact operator setup and service protocol. onboard status and plan are read-only, with text output by default and --format json for a structured packet. onboard bridge previews on every host; its apply form is restricted to the outer .SYSTEMX root and fails closed on Windows, where anchored directory handles are unavailable. It does not overwrite an existing root AGENTS.md or configure a provider. See provider and harness onboarding. The onboarding catalog includes sdk, ide, and cloud surfaces and a server-application credential consumer. Codex SDK is application-managed; Kiro CLI/IDE/Web and AWS CLI are distinct host paths; Claude Code, OpenCode, BLACKBOX, Gemini CLI, Cursor Agent, and Aider are documented manual/discovery examples. A catalog row, executable-name result, or first-time plan is not an Agent Y execution adapter or account authorization.

Agent X, Agent Y, and Agent Z

The 1.11.0-beta.4 release includes Agent X, Agent Y, Agent Z, Agent Alpha, Agent Beta, and Agent1 as distinct optional roles; their activation is explicit. Confirm the project's selected defaults are compatible before using these commands. Historical 1.8.9-alpha.1 installations have only the Agent X/Z interface.

bash .SYSTEMX/SYSTEMX.sh roles-init
bash .SYSTEMX/SYSTEMX.sh roles-init --apply
bash .SYSTEMX/SYSTEMX.sh agent-x list --limit 25
bash .SYSTEMX/SYSTEMX.sh agent-x due --as-of 2026-10-05T00:00:00Z
bash .SYSTEMX/SYSTEMX.sh agent-y providers
bash .SYSTEMX/SYSTEMX.sh agent-z policy
bash .SYSTEMX/SYSTEMX.sh agent-z prepare --kind prompt --subject initial-prompt \
  --revision PROMPT_HASH --evidence-revision CONTEXT_HASH --stage planned --apply
bash .SYSTEMX/SYSTEMX.sh agent-z score R_RETURNED_ID --apply
bash .SYSTEMX/SYSTEMX.sh agent-z compare Z_PREVIOUS_ID Z_CURRENT_ID

Use the complete returned record IDs instead of placeholders. Preparation and scoring preview by default; --apply persists a request/report. Fill all 100 answers in the saved request before interpreting its score; unknowns are zero points, not automatic passes. Each child command uses projects agent-x COMMAND --project NAME, projects agent-y COMMAND --project NAME, or projects agent-z COMMAND --project NAME. projects roles-init also requires a scope selector. See Agent X for event/schedule flags, Agent Y for CLI/PR channels, and Agent Z for fixed-policy review, validation, report preservation, and delta rules.

roles-init previews by default; --apply registers X/Y/Z and creates blank project-owned records. The distribution's registry still starts with only Agent 0. Role activation does not launch a model or provider process.

Agent Y CLI and pull-request channel

The task must already exist, be assigned to agent.y, and be in_progress. Verify the provider, local Git repo, actual account, base revision, allowed paths, and authority before applying. prepare previews without creating a worktree, running a CLI, pushing, or opening a PR. Repeat with --apply to save the channel and receive the returned Y-... ID. On native Windows, agent-y run ID --apply fails closed before provider or worktree mutation in this prerelease; core installer/record commands and Agent Y read-only inspection are separate from that execution limit. --branch NAME is optional; inspect the generated branch name in the preview if omitted. Repeat --allow-path REL for each permitted repository path. Agent Y pins the prepared CLI's canonical absolute path and file identity in private local state. run uses that path even if PATH changes and rejects a replaced or updated executable before starting it. Review the replacement and prepare a new handoff; the check does not pin the CLI's interpreter or dependencies and is not an OS sandbox. The example assumes an ignored .SYSTEMX/local/ directory inside the selected repository; keep the prompt file outside allowed code paths and ensure the target Git worktree is clean before preparing. For a Git-backed .SYSTEMX, prepare --apply requires effective ignore rules for state/agent-y/ sidecars and cleanup bundles, and refuses any already tracked file in that local state tree. A customized .gitignore is preserved; review it and verify the paths with git check-ignore before a run.

bash .SYSTEMX/SYSTEMX.sh agent-y prepare \
  --task TASK-001 --provider codex --repo /path/to/project \
  --base OBSERVED_REMOTE_BASE_BRANCH \
  --prompt-file /path/to/project/.SYSTEMX/local/agent-y/approved-task.md \
  --allow-path src/
bash .SYSTEMX/SYSTEMX.sh agent-y prepare \
  --task TASK-001 --provider codex --repo /path/to/project \
  --base OBSERVED_REMOTE_BASE_BRANCH \
  --prompt-file /path/to/project/.SYSTEMX/local/agent-y/approved-task.md \
  --allow-path src/ --apply
bash .SYSTEMX/SYSTEMX.sh agent-y run Y_RETURNED_ID --apply
bash .SYSTEMX/SYSTEMX.sh agent-y list
bash .SYSTEMX/SYSTEMX.sh agent-y show Y_RETURNED_ID
bash .SYSTEMX/SYSTEMX.sh agent-y validate

For a stranded running job after a controller crash, agent-y recover Y_RETURNED_ID previews a same-host dead-owner check; --apply marks that job failed only when the owner process is gone. It preserves its worktree and remote state for inspection. It does not kill, retry, or clean up a provider. An older job still prepared without a pinned executable cannot run on this version. After review, preview agent-y abandon Y_RETURNED_ID --reason TEXT, then apply the same command with --apply. It retires that unrun handoff without deleting a branch, worktree, or PR; reconcile the ledger and clean checkout before preparing a replacement. Already-run older jobs retain their normal PR/recovery commands.

This example keeps the handoff local. For an explicitly authorized PR task, add --open-draft-pr to both the preview and applied prepare commands instead of creating a second job. It opts into a push and draft PR only after a successful bounded CLI run. The PR can trigger Actions, webhooks, or spending rules in the target repository even though this template repository's GitHub Actions remains disabled; inspect the target repository before opting in. A CLI exit status and PR URL still require review of the actual diff/checks. Controller scope/Git checks do not replace configured project tests or prove application behavior. For a configured adapter, prepare --provider configured needs a reviewed --command ABSOLUTE_EXE; run Y_ID --apply requires --command ABSOLUTE_EXE again and supports repeatable --arg VALUE. Those local arguments stay in ignored host-local state; do not include credentials. The repeated executable must match the prepared canonical, unlinked file.

After Agent 0 or the user accepts the task and it is recorded done, a separately authorized pr-ready Y_ID --apply can mark the owned draft ready for review. This accepts the reviewed candidate change; when the original objective requires merge or live verification, keep those outcomes in dependent delivery tasks until observed. Agent Y has no merge command. After an externally authorized merge, pr-cleanup Y_ID --apply verifies the merged PR, accepted task, and exact owned branch/head. Its applied form creates and verifies a private local Git bundle under ignored state/agent-y/archives/, records its digest, then deletes only the unchanged owned branch/worktree. Retain the bundle separately before uninstall or host migration. Cleanup refuses to remove an ignored or untracked worktree file, including provider caches. If it stops after remote branch deletion, retain the verified archive and reconcile the local worktree, branch, and PR state manually. pr-ready refuses a moved remote base branch when its current SHA differs from the handoff's baseOid. Review the changed base and prepare a new handoff; do not treat a stale accepted task record as an authorization to promote the PR. For a cancelled task, pr-close Y_ID --reason TEXT --apply closes its abandoned owned PR without deleting the branch or worktree. Agent Y does not automatically delete unmerged cancelled work in this prerelease interface. Re-read GitHub after each action. When no owned PR exists, none of these PR commands applies; unpublished local work retains its branch/worktree for reviewed manual handling. If a push, PR create, ready, or close succeeds remotely but readback or the local job write fails, stop. Preserve the worktree and inspect the exact repository owner, base, branch, head SHA, PR identity, and state with read-only Git/GitHub queries. Reconcile the job and task manually before any retry; this beta provides no agent-y reconcile command. No command infers acceptance from an Agent Z score.

Workflow concepts and transport boundaries

Phases and waves are planning structure. Compatible ROOT defaults can record that structure through root node; canonical task fields remain unchanged. No cloud-sync, bot launcher, or automatic review-loop command is shipped. Use existing task, focus, role, and project commands with an explicit scope. ROOT planning and task delta, the one-shot guide, and the shared workspace guide distinguish saved observations from actual harness execution/transport.

AUTOBOT / Agent Alpha and local DATA: introduced in 1.10.0-alpha.2

Runtime command	Behavior
autobot init [--apply]	Preview/create missing detail seeds and optional agent.a registration; preserve existing bytes
autobot list	Read the fixed ten-slot catalog, not a model response
autobot context --bot autobot.design [--bot autobot.brand]	Bounded charter plus selected detail; no DATA scan
autobot request --caller agent.0 --purpose TEXT --input-revision REV --bot autobot.design [--task TASK-001] [--apply]	Preview/save selected identity and source fingerprints; reuse unchanged completed requests
autobot complete ABR-ID --summary TEXT --response-revision REV --evidence REF [--apply]	Preview/save original result evidence once; refuse stale source context or conflicting completion
autobot status [ABR-ID]	Recent request summaries, or selected document/result freshness for one ID
agent-a ...	Exact alias for autobot ...
data init [--apply]	Preview/add missing local DATA scaffolds; no replacement of existing files
data status / data audit	Bounded read-only effective local Git exclusion and tracked-payload report

The selectors for child use are projects autobot ... --project NAME and projects data ... --project NAME (or explicit --root). External installed routing uses systemx run --target OUTER --offline -- autobot ... or systemx projects --target OUTER -- autobot ... --project NAME. Preview precedes each explicit --apply; request/completion requires the selected agent.a activation. Caller labels remain unauthenticated local claims. See AUTOBOT examples and limits and DATA privacy and ignore exceptions.

ROOT planning and observed task delta

These optional commands require compatible 1.11.0-beta.4 defaults. root init previews; --apply creates missing records without replacing files. The detailed ROOT guide explains scope, vocabulary, status/acceptance boundaries, and examples.

Command	Purpose
root init [--apply]	Preview/add missing ROOT seeds in the selected scope
root status	Inspect selected records and bounded derived milestone task counts; no automatic milestone acceptance
root roster [--actor ACTOR] [--offset N] [--limit 1..50] [--decision-offset N] [--decision-limit 1..50]	Read-only registered agent, AUTOBOT, BOT, native-subagent decision, and recorded CLI-channel navigation; no provider probe or grant
root packet [--task TASK_ID] [--limit N]	Selected canonical task/request/node/card packet; 1–10 tasks, at most 64 KiB
root request --key KEY --kind rtask|stask --title TEXT --source-ref REF [--parent REQUEST_ID] [--apply]	Record origin or a bounded delegated request; STask names a parent
root node --key KEY --kind KIND --title TEXT --request REQUEST_ID [--parent NODE_ID] [--milestone M_ID] [--task TASK_ID] [--apply]	Reference a milestone/wave/phase/group/task/subtask/action structure; repeat task references as needed
root bind --key KEY --layer harness|bot --channel TEXT --item ACTUAL_ID --task TASK_ID [--supersedes BIND_ID] [--apply]	Bind an actual external identity to existing tasks; repeat --task for many-to-many mapping
root observe --key KEY --binding BIND_ID --raw-state TEXT --state STATE --revision REV --evidence REF [--expected-revision REV] [--at TIMESTAMP] [--apply]	Save a timestamped readback; repeat evidence references
root card --key KEY --task TASK_ID --provider TEXT --tool TEXT --purpose TEXT --input-revision REV --expected-evidence REF --permission-boundary TEXT --stop-condition TEXT [--request REQUEST_ID] [--apply]	Preview/save a tool-card contract; repeat task/evidence flags as needed; no tool execution
root delta [--task TASK_ID] [--layer harness|bot] [--limit N] [--max-age-seconds N]	Bounded read-only mapping/freshness/status comparison; default harness layer and 10 tasks, maximum 100

Normalized observation states are pending, running, blocked, completed, cancelled, unknown, and unavailable. A completed observation is not canonical acceptance. References/revisions/evidence remain caller-supplied records, not provider authentication or proof of live access. Child routing uses projects root COMMAND --project NAME or explicit --root. Installed forms are systemx run --target OUTER --offline -- root COMMAND and systemx projects --target OUTER -- root COMMAND --project NAME.

Without --expected-revision, an observation remains revision-unverified; with it, revision agreement is still a caller-declared comparison rather than a remote verification. --supersedes retains a corrected binding's prior history. Default freshness is change-based; an optional delta age limit is not a polling or retry schedule. Local menu option 21 and root-guide print the ROOT guide without initializing records or invoking a provider. Menu option 33 opens the read-only outer-scope Agent 0 roster; registered children use projects root roster --project NAME. The roster also appears as a stock/generated workbook tab, with different sheet layouts described in the roster guide.

Repeat --layer harness --layer bot to assess both layers; omitted layers are explicitly not_assessed. Do not create a placeholder bot mapping for a project that does not use one. Default delta task selection uses focus, otherwise active tasks first, with coverage/truncation counts for that selected candidate set. An item's expected state and canonical fingerprint cover all its bound tasks, including members outside the requested delta selection.

Binding supersession retains the same layer/channel. It can correct the same item's task mapping, or replace the external item with a new attempt while retaining the same canonical task set. Old bindings/observations remain in history and leave only the current comparison; no external cancellation occurs.

ROOT output caps apply to the actual final indented UTF-8 JSON response, including metadata and its trailing newline: 64 KiB for root packet, 128 KiB for other ROOT replies. An oversized mutation response is refused before its record is persisted; root init also preflights its applied reply before scaffold/log creation. This output rejection is separate from other I/O failure and recovery behavior. “SingleTask” is planning vocabulary represented by an action node; it is not an additional --kind spelling.