Phantom

A governed Windows 11 optimization system. Not a debloat script, not an autonomous agent — a proof-gated workflow that turns a manual optimization runbook into a safe, repeatable, reversible upgrade for any Windows 11 machine.

Phantom optimizes a Windows 11 laptop/PC like a real production machine — safer recovery, cleaner drivers, less idle drag, faster boot, better thermals, better battery health, a tighter browser/workflow stack — while holding one rule above all: start with diagnostics only, and change nothing without a reason, a risk level, a rollback path, and explicit human approval.

The agent's default power is read-only. Every state-changing action is classified, risk-scored, approved one at a time, executed, verified with before/after metrics, logged, and reversible.

---

The governed cycle

inspect → classify → plan → request approval → execute → verify → log → rollback if needed → preserve

Four phases, in order:

1. Phase 1 — Diagnostics only. Read-only inventory → system_AUDIT.md. Nothing changes.
2. Phase 2 — Decision table. Classify every item (Keep / Disable / Remove / Investigate / Never Touch) with a risk record + rollback → optimization_PLAN.md.
3. Phase 3 — Reversible optimization. Lowest-risk-first, one approved action at a time, before/after metrics logged each step.
4. Phase 4 — Advanced diagnosis. Only if idle CPU/RAM/disk/fan stays bad after Phase 3.

The safety contract — ALLOW / GATE / DENY

Every proposed action is classified before anything happens. See docs/SAFETY_MODEL.md for the full model.

• ALLOW (no approval; read-only): Get-* inventory reads, reports written into -Control, battery report, proposing plans and risk records.
• GATE (written risk record + explicit human "yes"; one action per approval): disable a startup entry, uninstall via vendor uninstaller, toggle visual effects / power profile / Storage Sense, set a service to Manual/Disabled (after identifying path + dependencies), Autoruns disable (snapshot first, never delete), DISM/SFC (corruption symptom + admin).
• DENY (never, regardless of who asks): full C:\ access, standing admin, reading or requesting BitLocker keys / passwords / banking pages / vault folders, registry cleaners, driver boosters, "ultimate debloat" scripts, BIOS/firmware flashing, deleting services/drivers by identity-unknown commands, disabling Windows Security entirely.

The secret firewall (absolute)

Phantom never reads, requests, stores, echoes, logs, caches, or transmits BitLocker / device-encryption recovery keys, Windows or browser passwords, password-manager vaults, banking/payment pages, 2FA seeds, or private keys — anywhere. Machine identifiers (serial, device ID, MAC, hostname) are sensitive and are redacted or hashed by default.

---

Quick start (Phase 1)

1. Create the control workspace and open PowerShell as a normal user (not admin):

   $Control = Join-Path $env:USERPROFILE '-Control'
   New-Item -ItemType Directory -Path $Control -Force
   Set-Location $Control

2. Run the read-only audit agent (agents/phantom_audit_agent.ps1):

   .\agents\phantom_audit_agent.ps1

   It writes system_AUDIT.md and battery-report.html into -Control. It changes nothing.

3. Pair the report with a 5-minute idle reading from Task Manager → Performance and the Startup-impact ratings from Task Manager → Startup apps.

4. Move to Phase 2: filter the §4 matrix from the runbook (docs/phantom_windows11_optimization_runbook.md) against the installed-app list to produce optimization_PLAN.md. The full governance method — contract, schemas, and deliverable templates — is in docs/PHANTOM_CONTROL_RUNTIME.md.

Give any AI/MCP/file tool access to the -Control folder only — never full C:\.

---

Repository layout

.
├─ README.md
├─ LICENSE                                   # Apache-2.0
├─ SECURITY.md                               # vulnerability reporting + secret-firewall policy
├─ CHANGELOG.md                              # notable changes (Keep a Changelog + SemVer)
├─ docs/
│  ├─ PHANTOM_CONTROL_RUNTIME.md             # the governance spec (contract, schemas, templates)
│  ├─ phantom_windows11_optimization_runbook.md  # the source knowledge (the manual runbook)
│  ├─ SAFETY_MODEL.md                         # the canonical ALLOW/GATE/DENY + secret-firewall reference
│  ├─ PUBLIC_RUN_GUIDE.md                     # public-safe, read-only Phase 1 run guide
│  ├─ RELEASE_PROCESS.md                      # versioning, release checklist, rollback/yank
│  ├─ SUPPLY_CHAIN.md                         # dependency stance + how to verify a release
│  └─ BRANCH_PROTECTION.md                    # recommended GitHub protection for main
├─ prompts/
│  ├─ PHANTOM_PROMPT_STACK.md                 # runs the agent (5 composed prompts)
│  ├─ PHANTOM_ENGINEERING_PROMPTS.md          # builds the platform (14 domain prompts, PHANTOM-CORE)
│  └─ PHANTOM_TECH_STACK_PROMPTS.md           # picks the technologies (42 integration-advisor prompts)
├─ agents/
│  └─ phantom_audit_agent.ps1                 # the read-only Phase 1 runner
├─ schemas/
│  ├─ mission.schema.json                     # the per-run mission packet
│  ├─ risk-record.schema.json                 # one record per gated action (what a human approves)
│  ├─ approval.schema.json                    # approval bound to a risk record + approver + time
│  └─ action-log.schema.json                  # append-only executed-action log line
├─ examples/
│  ├─ sample_system_AUDIT.md                  # filled Phase 1 report (synthetic, redacted)
│  ├─ sample_optimization_PLAN.md             # filled Phase 2 decision table
│  └─ sample_before_after_REPORT.md           # filled Phase 3 proof
├─ tests/
│  └─ zero-change-proof.md                    # safety-test matrix + the audit agent zero-change proof
└─ platform/
   └─ future-control-plane.md                 # forward-looking design (local-first; cloud coordinates only)

How the three prompt files relate

The same five invariants — least privilege, the secret firewall, no remote execution, reversibility, untrusted-input handling — hold across all of them:

• prompts/PHANTOM_PROMPT_STACK.md runs the agent.
• prompts/PHANTOM_ENGINEERING_PROMPTS.md builds the platform that hosts it, by domain (all inherit PHANTOM-CORE).
• prompts/PHANTOM_TECH_STACK_PROMPTS.md picks the concrete technologies, each with an honest FIT verdict.

The optimization work happens locally on the user's machine (the -Control folder, the read-only audit, the local approval gate). An optional cloud control plane does coordination and a redacted-evidence archive only — it never executes changes on a remote machine. See platform/future-control-plane.md.

Security & trust

Phantom warns users never to run random scripts from the internet — so it holds itself to the same standard: read it, verify it, run it read-only and non-admin. The trust docs:

• SECURITY.md — how to report a vulnerability, the secret-firewall policy, and the rule never to paste secrets into issues/PRs.
• docs/PUBLIC_RUN_GUIDE.md — the public-safe way to run the read-only Phase 1 audit: non-admin PowerShell, -Control-only scope, what the agent does and does not do.
• docs/SUPPLY_CHAIN.md — why Phantom avoids driver boosters / registry cleaners / debloat scripts, its minimal-dependency stance, and how to verify a release.
• docs/RELEASE_PROCESS.md — versioning, the release checklist, human-approved publishing, and the rollback/yank procedure.
• docs/BRANCH_PROTECTION.md — recommended branch protection for main (require PRs + the verify check + review; block force pushes; least-privilege Actions).
• CHANGELOG.md — notable changes across phases.

License

Apache License 2.0 — see LICENSE.