shadoWorker

Shadoworker Plugin

A shadow-driven development system for Claude Code that enables efficient work on large-scale projects through high-density information compression.

What is Shadoworker?

Shadoworker is a development pattern that maintains a parallel "shadow directory" containing compressed, high-density representations of your working files. These shadow files contain 10x the information density of regular files, allowing AI agents to maintain global context without overwhelming their working memory.

Key Benefits:

• Work efficiently on large codebases without losing context
• Maintain strategic oversight while delegating tactical execution
• Keep AI agents focused on architecture rather than implementation details
• Scale to projects with thousands of files

Use Cases:

• Large codebase development (Vibe Coding at scale)
• Novel writing and long-form content creation
• Comprehensive documentation projects
• Any work requiring massive context management

Core Concepts

The Three Iron Rules

1. Main agent never touches working files - Only operates on shadow files
2. Shadow drives working - Shadow files are the single source of truth
3. All working file changes go through subagents - Strategy and execution are strictly separated

Information Density

Shadow files compress information by 10x using clear, concise natural language. They're free-form and adapt to content type, focusing on intent and architecture rather than implementation details.

Granularity Principle

Prefer many small shadow files over few large ones.

Why?

• More precise change control
• Higher concurrency (more parallel subagents)
• Clearer separation of concerns
• Lower context consumption

Example:

❌ Bad: One large file
.shadow/src/auth.ts.shadow.md  (login, register, tokens, permissions)

✅ Good: Multiple focused files
.shadow/src/auth/login.ts.shadow.md
.shadow/src/auth/register.ts.shadow.md
.shadow/src/auth/token.ts.shadow.md
.shadow/src/auth/permissions.ts.shadow.md

Installation

For Claude Code CLI

1. Copy the shadoWorker directory to your Claude Code plugins directory:

   # Unix/Linux/macOS
   cp -r shadoWorker ~/.claude/plugins/
   
   # Windows
   xcopy shadoWorker %USERPROFILE%\.claude\plugins\shadoWorker\ /E /I
   

2. Restart Claude Code or reload plugins

3. Verify installation:

   You: "Load shadoWorker skill"
   

Manual Installation

Place the shadoWorker directory in your Claude Code plugins directory:

• Unix/Linux/macOS: ~/.claude/plugins/shadoWorker/
• Windows: %USERPROFILE%\.claude\plugins\shadoWorker\

The plugin includes:

• Skills: shadoWorker
• Agents: shadoWorker:init, shadoWorker:to-working, shadoWorker:to-shadow
• Tools: shadow-diff.sh, shadow-diff.ps1

Quick Start

Initialize an Existing Project

You: "Initialize shadow system for this project"

The shadoWorker:init agent will:

1. Create .shadow/ directory structure
2. Generate .shadowignore template
3. Scan your project and create initial shadow files
4. Provide initialization report

Daily Workflow

You: "Add user authentication feature"

The main agent (using shadoWorker skill) will:

1. Read shadow directory to understand project structure
2. Plan changes in shadow files (creating multiple small files)
3. Dispatch parallel shadoWorker:to-working subagents
4. Collect reports and verify results

Check Sync Status

You: "Check shadow sync status"

The agent will run shadow-diff to identify:

• Shadow files missing working counterparts
• Working files missing shadow counterparts
• Suggest sync actions

Components

shadoWorker Skill

The main skill that guides agent behavior. It:

• Enforces the three iron rules
• Encourages small, focused shadow files
• Defines best practices for shadow-driven development
• Coordinates subagent dispatch

shadoWorker:init Agent

Initializes shadow system for existing projects.

Input: Project root directory path

Output: Initialization report with file counts

Behavior:

• Creates directory structure
• Generates .shadowignore from template
• Scans working directory
• Creates initial shadow files (prefers splitting large files)

shadoWorker:to-working Agent

Materializes shadow changes into working files.

Input:

• Shadow file path and content
• Target working file path
• Operation type (create/update/delete)

Output:

• Operation result (success/failure)
• Brief report (1-3 sentences)

Behavior:

• Operates on one file at a time
• Translates high-density shadow into full implementation
• Reports errors honestly for main agent to fix

shadoWorker:to-shadow Agent

Compresses working files into shadow files.

Input:

• Working file path and content

Output:

• Generated shadow content
• Brief report