Skip to main content

Install ChaosEngine

ChaosEngine is SHAFT's project-local agent harness. It makes one canonical skill the entrypoint for supported coding agents, installs the matching host adapters, and provisions its tracked local tools without relying on a global machine setup.

Give the install command to your agent​

Open the SHAFT project that should receive the harness and give this command to Codex, Claude, Grok, Gemini, or another coding agent:

Install or upgrade ChaosEngine in this project from the latest commit of ShaftHQ/SHAFT_ENGINE main. Fetch and inspect https://raw.githubusercontent.com/ShaftHQ/SHAFT_ENGINE/main/chaos-engine/bootstrap.py, run it with Python 3, --project ., --repository ShaftHQ/SHAFT_ENGINE, and --branch main; then run Python 3 with .chaos-engine/install.py status --project . Do not stop until status reports the resolved 40-character commit and healthy core, host adapters, and local tools. Treat the installed ChaosEngine skill as the canonical harness and route existing agent guidance through it without deleting unrelated user content.

The agent chooses the available Python 3 command on Windows, macOS, or Linux. It must inspect the bootstrap before running it and report any network or permission boundary instead of bypassing it.

Verify and upgrade​

Run the installed status command from the project root:

python3 .chaos-engine/install.py status --project .

On Windows, use py -3 in place of python3. Re-run the same agent command to upgrade. The bootstrap resolves main to an immutable commit, validates the downloaded archive, and records its repository, branch, and commit provenance. If resolution, download, validation, or tool setup fails, ChaosEngine preserves the last verified installation.

The project may be a SHAFT Git checkout, another Git checkout, or a non-Git folder. The bootstrap uses the configured SHAFT upstream and never infers it from the consumer project's Git remote.

Read health and ownership​

Both status and doctor report each component's health with four capability fields:

FieldValuesMeaning
ownerinstaller, project, userWho may change or remove the component
scopeproject, repository, userWhere the component is shared
lifecyclereceipt-owned, persistent-data, derived-single-writer, user-managed-cacheHow the component is maintained
taskImpactrequired, advisory, optionalWhether its health affects ordinary task work

Memory, MemPalace, and Graphify have advisory task impact. An ordinary task can continue when any of them is missing, stale, corrupt, timed out, or inaccessible. Use one scoped query only when it answers a concrete question, verify any returned path against live files, and use targeted repository search before deciding impact. Do not retry, repair, refresh, poll, or watch a store as part of task completion.

Installation, upgrade, explicit maintenance, status, and doctor remain strict. An unhealthy selected component makes requested status or doctor health recovery-required. Advisory task impact does not weaken those operator checks.

Respond to reflection checkpoints​

ChaosEngine pauses implementation mutation after two attempted failures in one task. Different failure fingerprints require task-level reflection; the same fingerprint twice requires deep reflection. Read-only diagnosis, tracker updates, and a changed diagnostic check remain available, but an unchanged retry or third speculative fix does not.

Copy each hash after Sanitized fingerprints: in the checkpoint message. Use the session token printed by the lifecycle hook to append the bounded receipt:

python3 .chaos-engine/hooks/reflection.py receipt \
  --session-id SESSION_ID \
  --session-token SESSION_TOKEN \
  --json '{"schemaVersion":1,"taskId":"issue-123","trigger":"repeated-fingerprint","failureFingerprints":["COPY_HASH_FROM_CHECKPOINT"],"failedAssumption":"The unchanged retry would add evidence.","approachesCompared":["Inspect the bounded state","Change one diagnostic input"],"chosenExperiment":"Run the changed diagnostic check.","changedApproach":"Stopped the unchanged retry.","proofCommandOrCheck":"focused check","proofOutcome":"The focused check passed.","durableDisposition":"nothing-durable"}'

On Windows, use py -3 instead of python3 and quote the JSON for your shell. The receipt accepts bounded conclusions, not raw logs, prompts, credentials, or host paths. Knowledge stores and GitHub remain optional for this local control flow.

After more than one hour, finish implementation and delivery first. Then record the terminal receipt and use these exact labels in the final summary:

  • elapsed estimate
  • main time consumer
  • repeated failures or corrections
  • changed assumption or approach
  • successful proof
  • remaining risk or follow-up
  • learning loop disposition

Later work or failure invalidates an earlier terminal receipt.

What gets installed​

ChaosEngine installs and owns these project-local surfaces:

  • the verified core and canonical skill under .chaos-engine/;
  • native discovery adapters for Codex, Claude, Gemini, Copilot, and compatible agents;
  • a private dependency runtime for the tracked Memory, MemPalace, Graphify, and supporting tools;
  • receipts and transaction state used by status, repair, rollback, and uninstall.

It preserves unrelated project instructions, skills, configuration, and tool entries. Its self-learning flow queues only privacy-screened, confirmed lessons and contributes them upstream as reviewable GitHub issues, never as an automatic pull request.

The optional Maven Tools MCP uses an immutable user-managed cache. Multiple projects can reuse one verified JAR and receipt, and uninstalling ChaosEngine from a project never removes that cache. See the agent tooling cache runbook for status, purge, and manual population commands.