An orchestration framework for AI-assisted coding with Claude Code.
Structure your work. Enforce your rules. Ship with confidence.
→ Learn more at workscope.dev
AI coding tools are powerful, but using them effectively requires more than good prompts. Without structure, you get "vibe coding"—generated code that works until it doesn't, built on foundations no one fully understands. WSD brings discipline to AI-assisted development by organizing work into bounded units, loading relevant context deliberately, and verifying results through specialized review processes.
WSD doesn't replace your judgment. It gives you a framework for applying it consistently: breaking large projects into AI-appropriate workscopes, enforcing your project's rules automatically, and maintaining traceability across sessions.
Every unit of work is formally defined, sized for a single AI session, and tracked from assignment to completion. A workscope goes through a structured lifecycle:
- Assignment — Work is selected from your project's checkboxlists using a deterministic algorithm
- Context Loading — Relevant documentation and code files are identified and loaded
- Execution — The AI performs the assigned tasks with full context
- Quality Review — Specialized agents verify rule compliance, spec alignment, test coverage, and code health—with authority to reject work that doesn't meet standards
- Completion — Work is accepted, checkboxlists are updated, and an audit trail is preserved
Each workscope gets a unique ID, an immutable record, and a work journal documenting the session.
Your work items don't hide in a project management server—they live right in your project as checkboxlists scattered across your documentation. This means:
- Instantly editable — Change priorities by editing a markdown file
- Version controlled — Task history lives in git alongside your code
- Dynamically scheduled — The Task-Master agent constructs your schedule on the fly, following cross-document references to find the next appropriate work
- Parallel-aware — Multiple workscopes can run concurrently without conflicts
Five checkbox states ([ ] [%] [*] [x] [-]) enable hierarchical tracking across documents, from high-level phases down to individual implementation tasks.
WSD provides a documentation architecture that AI agents understand. Instead of hoping the AI finds the right context, the system deliberately surfaces relevant files:
- Feature specifications organized by feature in
docs/features/ - Tickets for discrete issues in
docs/tickets/ - Working memory in
docs/workbench/for active context - Core documents like your PRD and Action Plan in
docs/core/ - Rules and standards that agents are trained to follow in
docs/read-only/
Agents know where to look. Specifications stay in sync with implementation. Context flows to where it's needed.
Install WSD:
pipx install workscope-devIntegrate into your project:
wsd install path/to/your/projectThis adds WSD's workflow system to your project, including slash commands for Claude Code, documentation structure, and development tools.
Start your first session by running /wsd:init in Claude Code. See the User Guide for the complete workflow.
git clone https://github.com/rcgray/workscope-dev.git
cd workscope-dev
./wsd.py install path/to/your/projectWSD works with multiple project types and detects your stack automatically:
- Python — pytest, mypy, ruff, bandit integration
- TypeScript — ESLint, Prettier, TypeDoc integration
- JavaScript — ESLint, Prettier, JSDoc integration
- Polyglot — Mixed Python + Node.js projects supported
- Codeless — Documentation, research, and planning projects
- Python 3.10+ — Required for WSD tools
- Claude Code — The AI assistant WSD orchestrates
- Git — Recommended for rollback safety
For TypeScript/JavaScript projects, Node.js 18+ is also required.
After installation, guides are available in dev/wsd/:
| Guide | Description |
|---|---|
| User Guide | Daily usage, workflow lifecycle, commands |
| Integration Guide | Installation, customization, collision handling |
| Task Runner Guide | Development tools, health checks, unified commands |
| Update Guide | Updating WSD while preserving customizations |
Platform-specific setup:
MIT