Dispatch is an open-source project welcoming contributions. This guide covers local development setup, conventions, and testing.
Local Development
Repository Structure
The development source is located in skills/dispatch/. The .agents/skills/dispatch/ directory contains the installed version (from npx skills add).
Symlink Setup
For local development, a symlink makes the skill available as /dispatch when developing in the repo:
.claude/skills/dispatch → ../../.agents/skills/dispatch
Installation for Development
Clone the repository and install the skill locally:
git clone https://github.com/bassimeledath/dispatch.git
cd dispatch
npx skills add . -g # Install from local directory
skills/dispatch/SKILL.md are picked up immediately — Claude Code hot-reloads skills from disk.
Conventions
Task IDs
Format: Short, descriptive, kebab-case identifiers
Examples:
security-reviewadd-authfix-login-bug
Checklist Markers
Plan files use specific markers to indicate task state:
[x] — Completed[ ] — Pending (not yet started)[?] — Blocked (waiting for user input)[!] — Error (unresolvable error encountered)
Directory Structure
.dispatch/ directory: Ephemeral task state. Delete it to clean up completed tasks.
.dispatch/
└── tasks/
└── <task-id>/
├── plan.md # Checklist of work items
├── output.md # Task results (optional)
├── context.md # Worker context (legacy fallback)
└── ipc/ # Inter-process communication
├── 001.question # Worker questions
├── 001.answer # Dispatcher answers
├── 001.done # Acknowledgment markers
└── .done # Task completion marker
Config Location
Default location: ~/.dispatch/config.yaml
Auto-generated on first run with CLI detection and model discovery.
Skill Source
Canonical skill definition: skills/dispatch/SKILL.md
Do NOT modify SKILL.md for documentation changes. Update the docs/ directory instead.
Testing Changes Locally
1. Make Your Changes
Edit files in skills/dispatch/ or docs/.
2. Test the Skill
Open Claude Code in any project directory:
Then invoke the skill:
/dispatch "test task description"
3. Verify Behavior
Check that:
- Plan files are created correctly in
.dispatch/tasks/<task-id>/plan.md
- Workers spawn and execute tasks
- IPC communication works (questions/answers)
- Config changes are applied correctly
4. Test Documentation
If you modified documentation files:
Preview at http://localhost:3000 and verify:
- Content renders correctly
- Links work
- Code examples are formatted properly
5. Check for Broken Links
cd docs
mint broken-links
CI and Automation
Auto Docs Update Workflow
File: .github/workflows/update-docs.yml
Trigger: On every merge to main
Process:
- GitHub Action diffs the merge commit
- Passes diff to Claude (Sonnet model)
- Claude determines if
README.md or CLAUDE.md need updates
- If changes are needed, creates a PR with updates
- Uses
[docs-bot] in commit message to prevent infinite loops
Requirements:
ANTHROPIC_API_KEY repository secret- Permissions:
contents: write, pull-requests: write
Bot behavior:
- Only updates
README.md and CLAUDE.md
- Skips if no code changes detected
- Preserves existing style and formatting
- Creates PR (does not auto-merge)
Running Locally
You can simulate the workflow locally:
# Get diff from last merge
git diff HEAD~1..HEAD -- ':!node_modules' ':!dist' ':!*.lock' ':!.github'
# Use the diff to update docs (manual review)
claude -p "Review this diff and update README.md or CLAUDE.md if needed: [paste diff]"
Contribution Workflow
1. Fork and Clone
git clone https://github.com/YOUR-USERNAME/dispatch.git
cd dispatch
2. Create a Branch
git checkout -b feature/your-feature-name
3. Make Changes
Follow the conventions above.
4. Test Thoroughly
Run through the testing steps outlined above.
5. Commit
Use clear, descriptive commit messages:
git commit -m "feat: add support for custom backends"
git commit -m "fix: handle missing config.yaml gracefully"
git commit -m "docs: clarify IPC protocol sequence"
6. Push and Create PR
git push origin feature/your-feature-name
- Clear description of changes
- Why the change is needed
- How to test it
Additional Resources
Questions?
Open an issue on GitHub or start a discussion.