Repository navigation
Agent Y
Release status: Agent Y is included in the current 1.9.0-alpha.2 interface. Earlier 1.8.9-alpha.1 installations do not contain
agent-ycommands. Select a verified exact release; see Versions and changelog.
Agent Y is the optional CLI channel role (agent.y). Agent 0 can delegate one
bounded, existing task to a chosen external CLI assistant, such as Codex CLI,
Copilot CLI, or another provider actually installed on the user's machine.
Agent Y keeps the provider run, isolated Git work, and GitHub pull-request (PR)
handoff attributable to that task. The app or IDE running Agent 0 may also have
its own subagents; those workers and an external CLI are different execution
contexts. A role record does not launch either one.
The public template ships with only agent.0 registered. Preview roles-init,
then explicitly apply it with compatible selected defaults to add blank X/Y/Z
records in the chosen root .SYSTEMX or child .SYSTEMXP scope. This does not
run a CLI, open a PR, or rewrite existing records. The user or Agent 0 chooses
a provider per task. There is no preferred model, hidden fallback provider,
or automatic sharing of one provider's private context with another. For the
built-in Codex/Copilot adapters, prepare --model NAME can request a model
supported by the installed CLI and account. A configured adapter uses its
reviewed --arg values for model selection. Report the model observed in the
actual run when it matters to the task. Agent Y does not silently route across
models after a failure.
Alpha boundary: The saved channel is a coordination record. Real execution comes from the installed CLI, Git, GitHub CLI/API, and their existing permissions. Verify which command, account, repository, branch, and checkout are active before allowing writes. A task packet or draft PR is not proof that work ran or met acceptance criteria.
The controller has offline checks, but real Codex/Copilot provider execution and GitHub write paths have not been exercised end to end for this alpha. Treat the first authorized run in a project as a controlled trial with independent checks and remote-state readback.
Native Windows alpha limit: agent-y run Y-ID --apply refuses before
starting a provider or creating a worktree because descendant-process
termination has not been verified there. Provider detection, previews, and
record inspection remain available. This Agent Y execution limit does not
change the separate Windows installer/PowerShell or core record workflows.
Agent 0 remains the sole coordinator of the canonical WORK/TASKS.json ledger
and Master Plan. It selects a dependency-ready task, checks the current base
revision and actual authorization, assigns it to agent.y, and records
in_progress when the delegated task workflow begins. The Agent Y prepare
command requires that existing assigned, in-progress task and gives the CLI a
bounded packet:
| Channel input | What Agent 0 must establish |
|---|---|
| Scope | Exact .SYSTEMX or named .SYSTEMXP, task ID, acceptance criteria, dependency state, and stop condition |
| Provider | A CLI the user has installed and authorized for this task; the model or provider can differ from the app or IDE's model |
| Git target | Repository identity, base branch and observed commit, unique task branch, checkout or worktree, and permitted files |
| External authority | Whether the CLI may run, push a branch, open a draft PR after successful work, mark it ready, close an abandoned PR, or clean up the owned branch after a verified merge; merge requires a separate authorized process, while cancelled unmerged branches are retained for manual review |
| Return evidence | CLI exit status, changed paths, commit SHA, PR URL/number, and current remote state; Agent 0 must run and cite project checks separately |
No task owner string or Agent Y registry entry grants those permissions. Review the project's Access Matrix and the actual host/repository permissions. Keep tokens and credentials out of the channel record, prompts, logs, and PR body.
An applied Agent Y run uses an isolated worktree and a dedicated task branch for the assigned code change. It must inspect local edits before branching, avoid overwriting work, and record the verified base and head revisions. Worktrees isolate files but do not isolate ports, cloud resources, credentials, caches, or the canonical ledger. Give each task a distinct channel and a single integration owner. Do not have several CLI sessions edit the same branch or project records at once.
flowchart LR
A["Agent 0: authorized task packet"] --> B["Agent Y: selected Codex, Copilot, or configured CLI worktree"]
B --> C["Controller scope and Git checks; commit candidate"]
C --> D{"Zero CLI exit, scoped commit, and draft-PR opt-in?"}
D -->|Yes| E["Push task branch and open draft PR"]
D -->|No| F["Return evidence or failure without automatic PR"]
E --> G["Agent 0 project checks; Agent X events; optional Agent Z review"]
F --> G
G --> H{"Agent 0 accepts or cancels?"}
H -->|Accepted and PR exists| I["Ready decision; external merge; verified cleanup"]
H -->|Accepted without PR| N["Keep accepted local handoff; no PR action"]
H -->|Cancelled and PR exists| J["Close abandoned PR; retain branch and worktree"]
H -->|Cancelled without PR| O["Record cancellation; no PR action"]
H -->|Not yet| K["Keep channel open; record concrete next action"]
I --> L["Reconcile merged PR and exact owned head; optional authorized cleanup"]
Text equivalent: Agent 0 authorizes a task and provider. Agent Y runs the chosen CLI in an isolated branch and returns actual evidence. With opt-in, a zero CLI exit, and a scoped controller commit, it may push and open a draft PR before independent project checks. Agent Z may review the evidence; Agent 0 independently checks the result against the original task. The channel stays open until an accepted or cancelled decision is recorded. If there is no owned PR, acceptance or cancellation remains a local task decision and no PR transition applies. Ready, merge, abandoned close, and branch cleanup are separate GitHub actions, each requiring the applicable authority and remote-state readback.
An opt-in draft PR is a review handoff, not acceptance. Making a draft PR ready
does not merge it. Merging an accepted PR changes repository history; Agent Y
has no merge command. A merged PR with an accepted task can use a separate
pr-cleanup only after exact remote PR and owned branch/head checks. Its
applied form first creates and verifies a private local Git bundle under
state/agent-y/archives/, records its digest, then conditionally deletes the
unchanged owned branch and worktree. Retain that bundle separately before
uninstalling or moving hosts. Closing
an abandoned PR leaves its commits unmerged and is allowed only for a
cancelled task with an explicit reason; Agent Y retains its branch and worktree.
Agent Y must
not infer any of those operations from a high Agent Z score, a green local check,
or the mere existence of a draft PR. Agent 0 or the project owner must authorize
the specific action and verify the remote result afterward.
GitHub documents ready,
close, and
merge as distinct operations.
If the CLI task fails, times out, or stops with partial work, inspect the actual
process and files before retrying. Preserve the channel identity and evidence;
do not open a draft PR merely because a branch was created. If a network action
has an unknown outcome, query GitHub for the branch and PR before repeating it.
Avoid creating duplicate PRs for retries.
Remote push, draft-PR creation, ready, or close can succeed while the following
GitHub read or local JOBS.json write fails. Treat that as unknown, not
failed or safe to retry. Preserve the branch and worktree. Read GitHub and Git
without mutation to verify the exact repository owner, base branch, task branch,
head commit, PR number/URL, and current draft/open/closed/merged state. Compare
those facts with the saved job and original task, then perform a reviewed manual
reconciliation before any further action. This alpha has no
agent-y reconcile command and does not automatically repair partial remote
operations.
For a job stranded in running after a controller crash, preview
agent-y recover Y-ID. Its --apply form is allowed only when the recorded
owner is on this host and its process is confirmed gone. It marks the job failed
but preserves worktree and remote state for manual inspection; it does not kill
a live provider, retry a task, or delete a branch.
Preview activation first, then apply it in the selected root scope. For a named
child, use projects roles-init --project NAME and its --apply form.
bash .SYSTEMX/SYSTEMX.sh roles-init
bash .SYSTEMX/SYSTEMX.sh roles-init --apply
bash .SYSTEMX/SYSTEMX.sh agent-y providersCreate the task through the normal task workflow and assign it to agent.y.
After Agent 0 confirms its dependencies and starts the delegated workflow, the task
must be in_progress. prepare rejects a target repository with staged,
unstaged, or untracked changes. If task edits occurred in that same repository,
review and commit the coordination changes through the project's normal
process, then refresh and inspect the local origin/BASE tracking revision
before preparing. If .SYSTEMX is outside the code repository, still verify
the selected code checkout is clean. Use the real task ID, an absolute path to the intended
local Git repository, the observed base branch, a reviewed prompt file, and a
narrow relative allowed path. The prompt file must be a regular, unlinked file
inside that repository, at most 64 KiB; keep sensitive packets private and
ignored by Git. The example assumes that repository has a local .SYSTEMX
whose local/ directory is ignored; otherwise use a reviewed ignored path
inside the selected repository and outside the allowed edit scope. The portable
AGENTS/agent.y/JOBS.json stores task/provider
identity, allowed paths, Git base/head and PR references, state, and evidence
references. It does not store the raw prompt, provider transcript, or absolute
host paths. An ignored state/agent-y/Y-<id>.json file in the selected
.SYSTEMX or .SYSTEMXP stores that host's absolute repository, prompt, and
worktree paths and any configured executable arguments. Treat this sidecar as
private host-local execution state: do not put credentials in it, publish it,
or assume a synced JOBS.json can resume a run on another host. Whole-folder
backups or sync clients may still copy ignored files, so inspect their scope.
copilot also receives a temporary .agent-y-packet.md inside its isolated
worktree. The controller removes it after a normal return, but a crashed run
may leave that task packet behind; inspect retained worktrees before recovery,
backup, or disposal.
prepare previews by default; its --apply form saves a channel and returns
a Y-... job ID. The draft-PR flag is an
explicit opt-in to a later action after a successful run, not permission to
merge or delete anything.
Repeat --allow-path for other narrow paths; optionally supply --branch
or inspect the proposed generated branch in the preview.
The preview must be side-effect-free: it must not start a provider, create a
worktree, push, or contact GitHub to open a PR.
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/
# After inspecting the preview, apply the same packet to get Y_RETURNED_ID.
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 show Y_RETURNED_ID
bash .SYSTEMX/SYSTEMX.sh agent-y validate
# Only for a stranded running job after checking its owner process:
# bash .SYSTEMX/SYSTEMX.sh agent-y recover Y_RETURNED_ID
# bash .SYSTEMX/SYSTEMX.sh agent-y recover Y_RETURNED_ID --applySelect codex or copilot only after agent-y providers shows the CLI installed
and the account permissions are checked. A configured provider uses an
explicit reviewed absolute executable: pass --command ABSOLUTE_EXE at
prepare and again at run --apply, with repeatable --arg VALUE options
for that run. The provider listing cannot authenticate this adapter or decide
whether its flags are safe. Keep tokens out of those arguments and the sidecar.
Provider versions differ. If a selected CLI refuses the scoped permissions or
noninteractive mode, stop and report that limit; do not automatically retry
with broad all-tools access or silently switch providers.
The Codex adapter requests a worktree-write scope. Copilot and configured
adapters do not gain an equivalent operating-system sandbox from Agent Y.
Post-run allowed-path checks detect a changed local diff; they cannot reverse
network calls, external writes, or provider-side effects. Give each provider
only the host permissions and task resources it needs.
The example makes a local handoff without a push or PR. For an explicitly
authorized draft-PR task, add --open-draft-pr to both the preview and
applied prepare command in place of that local-only pair; inspect target
repository automation and cost first. Do not create a second job for the same
handoff just to change its PR policy.
run invokes the selected provider with the task prompt, checks the bounded
worktree result, and returns the observed CLI/Git/PR outcome. Read its job state
and GitHub after any interrupted or uncertain run before retrying.
On native Windows, this applied run intentionally refuses before provider or
worktree mutation in this alpha; use a verified supported host for CLI execution.
The controller's path and Git checks do not run or replace the project's
acceptance tests. Require original test/check evidence in the task packet and
review what actually ran before Agent 0 accepts the result. This alpha job
records CLI exit status, changed paths, commit/head and PR metadata. It does
not retain provider stdout/stderr or test output. Agent 0 must run and cite
independent project checks and use Agent X/Z records where relevant; a zero CLI
exit code cannot certify application behavior.
Opening a draft PR may trigger GitHub Actions, webhooks, or paid services in the
target repository, even though dotSYSTEMX's own GitHub Actions are disabled.
Inspect target-repository automation and cost rules before opting in. See
GitHub's workflow-trigger reference
and Actions billing guide.
After Agent 0 accepts the task with evidence and the canonical ledger says
done, a separately authorized pr-ready can mark the owned draft PR ready
for review. It does not merge the PR. After another authorized process merges
it, pr-cleanup verifies that remote outcome and exact ownership before
cleaning up the owned task branch or worktree. A cancelled task can instead
use pr-close with a reason to close its owned unmerged PR. That close retains
the branch and worktree; Agent Y does not automatically delete unmerged
cancelled work in this alpha interface. Unpublished local work likewise keeps
its sole branch/worktree for reviewed manual handling; Agent Y offers no
automatic no-PR cleanup command.
Define the delegated code task's acceptance criteria for the reviewed candidate change. If the original objective also requires merge, deployment, or live verification, preserve that objective in the Master Plan and track those outcomes as dependent delivery tasks. Close each delivery task only after its outcome is actually observed. Do not mark any unmet criterion complete just to unlock a draft-PR transition.
bash .SYSTEMX/SYSTEMX.sh agent-y pr-ready Y_RETURNED_ID --apply
# After an independently authorized merge has been verified:
bash .SYSTEMX/SYSTEMX.sh agent-y pr-cleanup Y_RETURNED_ID --apply
# On a cancelled task instead of the accepted path:
bash .SYSTEMX/SYSTEMX.sh agent-y pr-close Y_RETURNED_ID \
--reason 'Objective cancelled by project owner' --applyagent-y list and agent-y show Y_RETURNED_ID inspect saved channels. In a
child, use the projects agent-y ... --project NAME route so the job and task
resolve to the same .SYSTEMXP. These commands are alpha interfaces; use the
selected release's help for exact flags and verify the installed defaults
version before invoking them.
| Role | Owns | Does not imply |
|---|---|---|
| Agent 0 | Task selection, delegation, canonical ledger, integration, acceptance, and authority decisions | That a CLI or PR action has occurred |
| Agent X | Timestamped observations for CLI start/finish, branch push, draft/ready/merge/close decisions, and later live verification | A scheduler, GitHub webhook, or independent proof of the event |
| Agent Y | One selected external CLI task channel, provider/run identity, Git base/head and branch/PR handoff, return evidence, and authorized lifecycle actions | Provider installation, credentials, execution sandbox, or permission grant |
| Agent Z | One fixed-policy review of a prompt or changed result at a meaningful boundary | Automatic acceptance, merge, deployment, or another work loop |
Record actual GitHub state rather than desired state. A PR URL is evidence of a PR, but it does not establish that checks ran, the PR was merged, or the result is live. Agent X can record the observed event with its occurrence time, source revision, and original GitHub or CLI evidence reference. Agent Z may review the changed code and evidence using its existing 100 questions. Agent 0 decides whether the original acceptance criteria are met, whether another bounded task is needed, and whether an authorized PR transition should occur. Keep the task ledger as the only task-status authority.
- In Codex App or VS Code, Agent 0 reads the selected project's
.SYSTEMXstate and assignsTASK-001. App-native subagents may handle independent research or tests within the user's chosen worker ceiling. - For a distinct code scope, Agent 0 selects Codex CLI, Copilot CLI, or another available CLI for this task. It supplies the task packet, observed base revision, branch name, checkout, allowed files, required checks, and PR opt-in/authority boundary to Agent Y.
- Agent Y invokes the installed CLI through the host's real toolchain. It records process status and the scoped Git result, then, only when authorized and successful, pushes the task branch and opens a draft PR. It returns the PR number and URL plus the observed head SHA to Agent 0.
- Agent X records meaningful occurrences. Agent Z may review the relevant change
and evidence. Agent 0 runs/cites the project's required checks, independently
checks the candidate change, and moves
the canonical task to
needs_review, then todoneonly on acceptance. - Agent 0 makes a separate decision to request review, authorize an external merge, or close an abandoned PR. Agent Y performs only its supported and authorized ready/close action; after verified merge and acceptance, it may perform guarded branch cleanup. It reads GitHub back and records the final disposition. A cancelled unmerged branch stays available for reviewed archival or manual disposition.
This also works when the app and CLI use different model providers. The shared
contract is the explicit task packet, repo revision, scoped artifacts, evidence,
and handoff—not a claim that one model inherits another model's hidden context.
App-native subagents and external CLI runs consume a shared project budget
for concurrent work, tokens, tool time, and contested resources. An Agent Y job
does not grant another free set of worker slots. .SYSTEMX does not enforce a
cross-harness scheduler; Agent 0 must track this allocation. The CLI session has
separate runtime memory; only deliberately saved and verified notes/evidence cross into
the selected .SYSTEMX or .SYSTEMXP records.
For a chat-only environment without local CLI or GitHub access, keep the channel
as a proposed handoff and use an authorized human or external host to execute it;
do not mark it as run.
In SYSTEMX PROJECTS, identify the registry name and child
record path in every packet, for example Project-A:TASK-001 at
.SYSTEMX/Projects/Project-A/.SYSTEMXP. Equal task IDs in two children are
different tasks and must not share a channel or PR association accidentally.
The outer Agent 0 coordinates cross-project changes. The child Agent 0 owns its
own task ledger and acceptance. Git branch/PR state belongs to the actual
repository, which may not have the same boundaries as .SYSTEMXP; verify that
mapping in the System MAP.
A local .SYSTEMX lock is not a distributed Git, Drive, or cloud lock. Multiple
app sessions or CLIs must establish one canonical writer and integrate by
reviewed changes. See shared workspaces,
subagent processing, and security.
.SYSTEMX · DOT SYSTEMX · Maintained by Wayne Tech Lab LLC · Repository · User manual · Prompt cookbook · MIT license
Beta 1.11.0-beta.4 prerelease — validate the selected release in your project. Release policy. Project records, configured commands, and verified evidence determine the state of each adopted project.
DOT SYSTEMX · User manual
1. Start here
- Getting Started Easy Mode
- Complete Synergy Map: inputs, processing, outputs
- Current beta product film: chapters and scenes
- The Guided Folder: historical 4K walkthrough
- Start with a Folder: 4K animated guide
- Introduction video and archived poster
- Advanced walkthrough: inside the coordination layer
- Choose a workspace
- Agent 0 roster: roles, bots, and CLI paths
- Agent 0 and toolchain direct I/O
- First-time setup
- Provider and harness onboarding
- Daily workflow
- One-shot project guide
- Shared workspaces, clouds, and bots
- Historical use-case workflows
- Four current system maps
- Current maps, seven agent guides, and atlas
- Film engineering master: original companion
- Agent guide text and CLI flows
- Visual guide and historical diagrams
- New chat setup prompt
- Prompt cookbook
2. Work and continuity
- SYSTEMX PROJECTS
- AUTOBOT and Agent Alpha: Tier 2
- Local DATA storage
- Planning and memory
- ROOT planning, rules, and task delta
- System MAP
- Access Matrix: 20 standard entries
- Agent Beta, Agent1, and Agenda
- Task workflow
- Agent X: events and time
- Agent Y: CLI and PR channels
- Agent Z: fixed review
- 100 review questions
- Agent 0 and subagents
- Subagent processing
- Advanced use cases
- Evidence and acceptance
- Anti-drift and long-running work
- Tokens, cost, and time
3. Setup and maintenance
- Project / VS Code
- OS directory
- Google Drive
- LLM chat
- Exact casing and alias
- Installation and updates
- Upgrading
- Uninstall and cleanup
4. Advanced reference
- Standard format
- Technical Guide
- Stack Guide
- Library integration
- CLI and Tools
- Command reference
- Configuration and quality
- Operations and troubleshooting
- Security and support
- Code review and readiness
5. Project information