Shadow Refactor

Create an anonymized copy of your code for AI-assisted or external editing, then review and synchronize the changes back into your original VS Code workspace.

Initialize → Configure simple_terms → Export Bundle → External Edit
                                                  ↓
Workspace ← Review & Sync ← Export Bundle

Important — review before sharing

• Shadow Refactor is rule-based tooling, not a guarantee of anonymity.
• You must configure the rules, inspect every exported file, and decide whether the export is safe to share.
• The developer is not responsible for sensitive information disclosed because of incomplete rules, unsupported syntax, missed content, or an export that was not adequately reviewed.

How it works

┌────────────────────────── ORIGINAL WORKSPACE ──────────────────────────┐
│ Real source + issues/ + .shadowrefactor/{rules, lock, baselines}       │
└───────────────────────────────┬────────────────────────────────────────┘
                                │ Export Anonymized Bundle
                                │ transform content + paths, run checks
                                ▼
┌────────────────────────── ANONYMIZED EXPORT ───────────────────────────┐
│ Anonymous source + anonymous issue documents + independent Git history │
│                                                                        │
│ AI/external editor: read task → edit code → test → write result doc    │
└───────────────────────────────┬────────────────────────────────────────┘
                                │ Export Bundle → Workspace
                                │ diff + reverse mappings
                                ▼
                       ┌───────────────────┐
                       │ Human review gate │
                       └─────────┬─────────┘
                                 ▼
                 Accepted code + restored result document

The original workspace holds the real names and local mappings. Share the export only after inspecting it. The diagram shows the recommended VS Code review workflow: choose Review staged changes (Recommended) when syncing back. The separate Apply directly to workspace option bypasses staged review.

The four-command workflow

Most users only need these commands:

1. Shadow Refactor: Initialize Workspace
2. Shadow Refactor: Export Anonymized Bundle
3. Shadow Refactor: Sync Changes: Export Bundle → Workspace
4. Shadow Refactor: Sync Changes: Workspace → Export Bundle — only when the original workspace changes while an export is active

Which sync command should I use?

Read the arrow from left to right: it shows where changes are going.

Quick start

1. Initialize the workspace

Run Shadow Refactor: Initialize Workspace. This creates .shadowrefactor/ with the recommended starter configuration. No other setup command is required before your first export.

2. Add real project terms in simple mode

Open .shadowrefactor/rules.yaml. For most projects, use mode: simple and list every project-specific term that must be replaced:

version: 1
mode: simple
anonymous_prefix: shrfssac
simple_terms:
  - InternalProductName
  - CustomerAccount
  - PrivateServiceName

simple_terms handles common style variants automatically:

• CustomerAccount
• customerAccount
• customer_account
• CUSTOMER_ACCOUNT
• customer-account

Start with product names, company names, internal services, domain concepts, customer terminology, and other identifiers that reveal the original project. Use simple_map only when a term must receive a specific alias.

Simple mode is the recommended path because it is explicit, predictable, and easy to review. It does not discover every sensitive term automatically.

Include task and result documents

New workspaces include Markdown files by default; no extra rule change is needed for task and result documents. If you initialized an older workspace, remove .md from its existing ignore.extensions list in .shadowrefactor/rules.yaml to include Markdown. Initialization preserves existing rules. Choose the whole workspace for this workflow, or include both the relevant source folders and issues/ in config.json under scope.includedPaths. A source-folder-only export will not include a sibling issues/ directory. Confirm that the exported task exists before starting the AI.

3. Export and inspect

Run Shadow Refactor: Export Anonymized Bundle, then choose the scope and a new, empty destination outside the original project. Use Workspace → Export Bundle to update an existing bundle; a new export into a populated folder can fail with a path collision.

Before sharing the export:

• Search for project, company, product, customer, domain, hostname, and endpoint names.
• Inspect filenames, paths, comments, strings, configuration, fixtures, and generated data.
• Add anything missed to simple_terms, export again, and repeat until satisfied.

4. Edit and sync back

Edit the exported bundle with your preferred AI or development tool. Then run:

Shadow Refactor: Sync Changes: Export Bundle → Workspace

Select the export, review the staged changes, and accept only the changes you want.

5. Keep an active export current

If the original workspace changes while the exported bundle is still being edited, run:

Shadow Refactor: Sync Changes: Workspace → Export Bundle

Resolve and commit any Git conflicts in the export repository before continuing or syncing changes back.

Recommended AI collaboration protocol

Keep task instructions and AI hand-offs inside the synchronized project instead of moving them through chat manually:

1. Write the task as issues/<id>-task.md in the original workspace.
2. Export or run Workspace → Export Bundle so the task and code use the same anonymous vocabulary.
3. Give the AI only the exported task document and exported repository.
4. Ask it to edit the export and write issues/<id>-result.md there.
5. Run Export Bundle → Workspace, choose Review staged changes (Recommended), and review the code and document. Read the restored result yourself or with an assistant already authorized to see the original project; do not send it back to the export-side AI.

Use a separate AI session opened only on the export. The export directory is not a sandbox: limit the AI tool's filesystem access so it cannot read the original workspace or local mapping files. Use the actual exported task path in the prompt below; paths can also be anonymized.

Read issues/042-task.md and complete the work in this repository.
Use only the terminology and files available in this exported workspace.
Do not guess or reconstruct original names.
Before finishing, write issues/042-result.md with the implementation summary,
changed files, tests and results, assumptions, risks, and remaining work.

This document loop helps preserve consistent terminology. Mixing a real task description with anonymized code can disclose original terms, make symbols impossible for the AI to find, or reintroduce real names into the export. Conversely, copying a chat-only answer back by hand can leave anonymous aliases in the original project. Keeping both task and result documents in the bundle lets the same deterministic mappings translate the entire collaboration in both directions.

Task and result documents

Keep durable instructions under an included issues/ directory:

issues/
├── 042-task.md
├── 042-result.md
└── archive/

The task should contain enough context that no un-anonymized follow-up prompt is necessary:

# Task

## Objective

Describe the desired outcome.

## Relevant scope

- Files or modules the AI may change
- Files or modules it must not change

## Acceptance criteria

- Observable behavior and required edge cases

## Verification

- Tests, linters, or build commands to run

## Required hand-off

Write `issues/042-result.md` with the summary, changed files,
test results, decisions, assumptions, risks, and remaining work.

The AI's result should be operational rather than conversational:

# Result

## Summary

- What was implemented and why

## Changed files

- `path/to/file` — purpose of the change

## Verification

- `test command` — passed, failed, or not run

## Decisions and assumptions

- Important implementation choices

## Risks and remaining work

- Known limitations or follow-up tasks

Operating discipline

• Make sure issues/ is included in the export scope.
• Write or update the task in the original workspace, then export or synchronize Workspace → Export Bundle.
• Inspect the exported task before sharing it. If real terms remain, update simple_terms and refresh the bundle.
• Start the AI tool from the export directory. Never provide .shadowrefactor/, mapping data, private paths, or the original task.
• If more context is needed, add it to the original issue and refresh the export instead of pasting real terminology into chat.
• Require the result document before the AI finishes.
• Synchronize Export Bundle → Workspace and use the review view before accepting anything.
• Treat the synchronized result document—not the chat response—as the authoritative hand-off.

At the review gate, confirm that only intended files changed, reported tests are reproducible, no guessed real names were introduced, and no anonymous alias remains where a restored project term is expected.

Why the mapping file stays local

anon.lock.json is currently stored as plaintext JSON and makes aliases deterministic and reversible. It can contain original-to-anonymous mappings, so it is sensitive and must never be exported, committed publicly, attached to a support request, or given to an AI provider.

The lock is stored beside the original source. Someone who can already read that workspace can normally read the source too, so encrypting only the lock would not by itself secure a compromised workspace. At-rest encryption is useful defense in depth when local state might be backed up or exposed separately, but a meaningful design must keep its key outside the file, such as in the operating system keychain. The primary controls remain filesystem access, device encryption, export exclusion, and human inspection.

What stays local

• Transformation and policy scanning run locally.
• The extension does not include telemetry or automatically upload code.
• Reversible mappings remain under .shadowrefactor/.
• Mapping files are excluded from export bundles.

Content you manually send to an AI provider or another party is governed by that party's privacy and retention terms.

Security and user responsibility

Shadow Refactor reduces accidental disclosure but cannot determine whether an export is anonymous enough for your organization, contract, regulation, or threat model.

You are responsible for:

• Defining complete project-specific rules
• Reviewing the entire export, including paths and non-code files
• Running required secret scanners, DLP tools, or organizational checks
• Deciding whether and where the export may be shared
• Reviewing all changes before applying them to the original workspace

Detection is heuristic and rule-based. It is not a replacement for security review, legal review, a dedicated secret scanner, or a DLP product.

Do not disclose suspected vulnerabilities publicly. Contact the publisher through the Marketplace listing to arrange a private reporting channel.

Requirements

• VS Code 1.85 or newer
• Git available on PATH for export and synchronization workflows

Configuration

Shadow Refactor stores workspace state under .shadowrefactor/:

• rules.yaml — terms, mappings, preservation, and anonymization rules
• config.json — include/exclude scope and export settings
• policy.json — policy and leak-scan settings
• collab.json — deterministic collaboration settings
• anon.lock.json — reversible local mapping data
• state.json — local extension state

Guided Setup, side-by-side views, policy reports, coverage reports, draft mode, and advanced mappings remain available but are optional.

Known limitations

• Results depend on project-specific rules and user review.
• Complex or unsupported syntax can leave terms unchanged.
• Modified or added binary files cannot be synchronized through patches.
• Round-trip synchronization requires .shadowrefactor/baselines in the original workspace.
• The shadow:// editor does not support every creation, deletion, or rename workflow.
• Complex template expressions can require explicit rules.

Support

Use the Q & A tab on the Marketplace listing for help, reproducible bugs, and feature requests. Remove source code, mappings, secrets, tokens, and private paths before posting.

License

Shadow Refactor is proprietary software. You may install and use it under the included license. The license includes explicit warranty, anonymization, disclosure, and liability disclaimers. Redistribution, modification, and reverse engineering remain restricted. See the LICENSE included with the extension. Third-party components remain under their original licenses listed in THIRD_PARTY_NOTICES.md.