Setting Up WSD

What Is Workscope-Dev?

Workscope-Dev (WSD) is a framework for AI-assisted software development. It provides a structured system of files, agents, commands, and workflows that you install into any software project to create a productive, repeatable collaboration between human developers and AI coding assistants.

WSD is a collection of Markdown documents, standard-library scripts, and AI assistant configuration files. There are no external dependencies, no build steps, and no runtimes to configure. You install it, and it works. You remove it, and nothing breaks. Your project remains fully functional either way.

What WSD provides is an orchestration layer. It manages how work is assigned to AI assistants, how they prepare for tasks, how they execute them, and how the quality of their output is validated before you accept it. This orchestration is what separates structured AI-assisted development from ad hoc prompting.

WSD is not a package manager or a framework you build on top of. It augments your project by adding directories alongside your code. The system does include rules and instructions, but it backs them with enforcement mechanisms and validation agents that hold work to a standard before you accept it.

WSD is designed for developers who have moved past the honeymoon phase with AI coding assistants. You know AI-assisted development works, but you also know it needs guardrails. You want structure that makes the results consistent.

Prerequisites

Before installing WSD, ensure you have the following:

• Python 3.10+ — Required for WSD scripts and the task runner
• Git — Strongly recommended for rollback safety and version tracking
• Claude Code — The AI assistant WSD is designed for

For TypeScript or JavaScript projects:

• Node.js 18+ — Required for language-specific health checks and tooling

For codeless projects (documentation, research, planning):

• No additional prerequisites beyond Python, Git, and Claude Code. WSD’s workflow features work normally without any programming language installed. See the Codeless Project Guide (dev/wsd/Codeless-Project-Guide.md) in your WSD installation for detailed setup.

Installation vs. Integration

WSD follows a two-step model that separates getting WSD onto your system from putting it into a specific project.

Installation is getting WSD onto your system. This happens once. The recommended approach is pipx install workscope-dev, which provides a global wsd command that works from anywhere on your machine. Alternatively, you can clone the GitHub repository for a more hands-on approach — this gives you the source distribution directly.

Integration is inserting the WSD framework into a specific project’s root directory. If you installed via pipx, run wsd install <path> from anywhere. If you installed via repository cloning, run ./wsd.py install <path> from the clone directory. You install WSD once, but you integrate it into as many projects as you like.

This distinction matters because WSD is a file distribution system. The global installation is the source of those files. Each integration copies them into a project, creates a manifest (.wsd) for tracking, and configures the project for AI-assisted development. When a newer version of WSD is released, you update the global installation first, then update each project’s integration separately.

Integrating WSD into Your Project

The recommended path for a first experience is a new, blank project. This lets you see exactly what WSD provides without worrying about file conflicts in an existing codebase.

Create a new folder and start with clean git state. If you were integrating into an existing project, you would commit any pending changes first — this gives you a clean rollback point if anything goes wrong.

Run the install command to integrate WSD into your project:

# Into a new project
mkdir my-project
wsd install my-project

# Into an existing project (from anywhere)
wsd install /path/to/my-project

# Into the current directory
wsd install .

WSD performs collision detection before copying any files. If your project already contains files that would conflict with WSD templates, the installation stops and reports the collisions. Your existing files are never modified during this check. You can resolve collisions by renaming or moving the conflicting files, then retrying the installation. For details on collision resolution strategies, see the Integration Guide (dev/wsd/Integration-Guide.md) in your WSD installation.

After a successful installation, commit immediately:

cd my-project
git add .
git commit -m "Installed WSD 1.x.x"

This creates a clean checkpoint. If you ever want to undo the installation, a single git revert takes you back to exactly where you were.

After committing, re-run Claude Code’s own /init command (not WSD’s /wsd:init) so that Claude Code can update its CLAUDE.md file to reflect the newly integrated project structure.

You can preview what an installation would do without making changes by using --dry-run, and you can enable detailed logging with --verbose to see exactly which files are being copied.

Running /wsd:setup

The essential first step after integration is running /wsd:setup in a Claude Code session. This interactive command detects your project’s languages, configures tooling, checks your .gitignore for recommended WSD entries, and ensures WSD’s commands work correctly.

Why this matters: several third-party tools have default behaviors that can be destructive if they run without configuration. A documentation generator might overwrite your docs/ directory. A linter might scan directories it shouldn’t. /wsd:setup places defensive configuration files that prevent these default behaviors, ensuring tools only operate where they should.

On a blank project, /wsd:setup will configure a “codeless project” initially — a minimal setup with check_dirs = [] that tells WSD’s quality tools there is no code to check yet. This is fine. Once you have written code and established a test suite, you will re-run /wsd:setup to detect the changes and enable the full suite of quality checks.

After setup completes, commit the configuration:

git add .
git commit -m "Set up WSD"

Customizing Your Project Introduction

The most important customization you can make after installation is filling in the project introduction tag. Open .claude/commands/wsd/init.md and find the <WORKSCOPE-DEV wsd-init-project-introduction> tag. Replace the default content with a brief overview of your project — what you are building, what technologies you use, and how you approach development.

This tag is the first thing every AI agent reads about your project when a new session begins. An agent without project context makes worse decisions because it does not know your architecture, your conventions, or your goals. A well-written project introduction grounds every agent session in the reality of your specific project.

Keep the introduction focused and practical. Write as if explaining your project to a new team member: what the project does, what stack it uses, and where to find the key documents. A few sentences to a short paragraph is enough. You can also direct agents to read your PRD for deeper context once you have created one.

WSD ships with pre-release settings that prevent agents from prioritizing backward compatibility during active design evolution. This is helpful when your project’s architecture is still taking shape, but counterproductive once you have shipped and need to maintain stability. If your project is already mature, look for the pre-release rules section in docs/read-only/Agent-Rules.md and remove them from their <WORKSCOPE-DEV> tag so that agents respect backward compatibility as they normally would.

What’s Next

You now have WSD integrated and configured. The next step is creating your project’s core documents (a PRD and an Action Plan) and running your first workscope cycles. The Your First Project guide walks you through this process, from creating foundational documents to experiencing the full workscope cycle with the QA gauntlet active.