Managing Your Installation

Updating WSD

Updating WSD is a two-level process that mirrors the installation model. WSD lives in two places, as a tool on your system and as a collection of files inside each project, and each level updates independently.

The first level is the tool itself. If you installed WSD via pipx, running pipx upgrade workscope-dev pulls the latest version of the WSD package onto your system. This gives you access to the newest framework files, bug fixes, and improvements, but it does not change any of your existing projects. Your projects continue running whatever version of WSD they were integrated with until you explicitly update them.

The second level is the project integration. Running wsd update <directory> (or equivalently wsd install <directory>, which auto-detects an existing installation and performs an update) upgrades a specific project’s WSD files to match the version you have installed on your system. During this process, files are added, removed, or updated as needed — while your customizations are preserved through the content preservation system described in the next section.

The --dry-run flag is your preview tool. Running the update command with --dry-run shows exactly what would change — files to add, delete, update, or skip — without modifying anything. The output uses a clear symbol system: + for additions, - for deletions, ~ for updates with content preservation, and = for protected files that will not be touched. This preview is especially valuable before your first update or after a long gap between updates.

The safety practice is straightforward: commit before updating. A clean git state before the update means you can review the diff afterward and roll back with a single git checkout . if anything looks wrong. The recommended workflow is commit, dry-run, review, apply, verify, commit — and since updates are idempotent, you can always run the same update again if something goes wrong.

Two commands that sound similar but do different things deserve clarification. wsd update upgrades the WSD framework files in your project — the agents, commands, scripts, and documentation templates that WSD provides. wsd sync is a standard development command that synchronizes your project’s own dependencies (equivalent to uv run sync or pnpm install depending on your project type). One updates WSD itself; the other updates your project’s packages.

After updating, consider whether /wsd:setup needs to run again. Most updates are seamless — the content preservation system handles everything automatically. But if an update introduces changes to setup-related documentation or configuration patterns, re-running /wsd:setup in a fresh Claude Code session ensures your project’s tooling configuration stays current. The update output will note when this is recommended.

For the complete update reference including verbose mode, error recovery, and troubleshooting, see the Update Guide (dev/wsd/Update-Guide.md) in your WSD installation.

Content Preservation

The content preservation system is how WSD can improve its templates, fix bugs in scripts, and add new agents — while your customizations survive intact. It works through two complementary mechanisms: tagged content regions and file-level protection.

WORKSCOPE-DEV tags mark sections of WSD files that contain your project-specific content. A tagged region looks like this:

<WORKSCOPE-DEV my-project-config>
Your project-specific content here
</WORKSCOPE-DEV>

When an update runs, everything outside these tags gets replaced with the new template version, but the content inside the tags is preserved exactly as you wrote it. The process is precise: the update system reads your current file, extracts your tagged content, applies the new template, and restores your content into the corresponding tags. The surrounding instructions might change, new sections might appear, but your customizations remain untouched.

The most important tagged region is the project introduction in .claude/commands/wsd/init.md — the first thing every AI agent reads about your project. Your project-specific rules in docs/read-only/Agent-Rules.md are similarly tagged. You customize these once, and they persist through every future update.

If a new WSD version adds a tag that did not exist before, you receive the template’s default content for that tag and can customize it at your leisure. If a tag is removed from the template in a new version — which is rare and typically only happens during major structural changes — content in that tag is discarded.

The second mechanism is file-level protection through the no_overwrite flag. Certain files are installed once and never modified by updates, regardless of what changes in the WSD source. These are files that you are expected to completely own: your Action Plan, your PRD, your Design Decisions, and so on. The complete list is defined in wsd.json, and the dry-run output shows these files in the “Files to Skip” section so you always know what is and is not being touched.

Together, these mechanisms mean you can stay current with WSD improvements without maintaining a fork or worrying about losing your work. You can keep updated with the latest WSD improvements without managing your customizations.

Uninstalling WSD

Running wsd uninstall <directory> cleanly removes WSD from a project. The command reads the .wsd manifest to identify every file WSD manages and removes them systematically.

The default behavior preserves files marked with the no_overwrite flag — your Action Plan, PRD, Design Decisions, as well as the files created through your use of WSD like work journals, workscope records and other files that represent your project’s unique content rather than WSD infrastructure. These are files you created and own. WSD installed the initial templates, but the content is yours, and the default uninstall respects that distinction. The --all-files flag overrides this protection and removes everything WSD tracks, including no_overwrite files.

Like the other lifecycle commands, --dry-run is available for previewing what would be removed before committing to the operation. The preview shows which files will be deleted and which will be preserved, giving you full visibility before anything changes.

One thing the uninstall does not remove: configuration changes made by /wsd:setup. When you ran setup, it may have added entries to your .gitignore, created configuration sections in pyproject.toml or package.json, or placed defensive configuration files to prevent tool conflicts. These changes are part of your project’s configuration now, not WSD files, and they remain after uninstall.

After uninstalling, your project continues to work exactly as it did before. WSD adds directories alongside your code, but it doesn’t replace or reorganize your project structure. Remove WSD and your code, your tests, your build system, and your dependencies are all exactly where they were. The directories WSD added are gone, and your project is lighter by exactly the weight of the framework files. Empty directories left behind by file removal are cleaned up automatically.

The .wsd Manifest

The .wsd file is a JSON manifest that WSD creates when it integrates into your project. It tracks the installed version and a complete list of every file WSD manages. This manifest is what makes updates, dry-runs, and uninstalls possible. It is how WSD knows which files belong to it and which belong to you.

The manifest should be committed to git. It is small, changes only during install and update operations, and provides the essential state that lifecycle commands need to function correctly. Without it, WSD cannot determine what is installed, what needs updating, or what should be removed.

You will also notice .wsdkeep files in otherwise-empty directories. These are placeholder files that preserve directory structure across git clones, since git does not track empty directories. They serve no other purpose and are cleaned up automatically during updates and uninstalls when the directories they protect gain real content or are no longer needed.

The global wsd command — installed via pipx install workscope-dev — uses an intelligent routing system to direct commands to the right place. Lifecycle commands (install, update, uninstall) along with --help and --version are always handled by the global package, regardless of where you run them. This is what allows you to run wsd install /path/to/project from anywhere on your system. All other commands — test, lint, health, format, and everything else — are forwarded to the local wsd.py script in your current project directory. This routing means a single wsd command does the right thing in every context: managing installations from anywhere, running project commands from within a project.