Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bassimeledath/dispatch/llms.txt

Use this file to discover all available pages before exploring further.

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). For local development, a symlink makes the skill available as /dispatch when developing in the repo: 
.claude/skills/dispatch → ../../.agents/skills/dispatch
This allows you to test changes immediately without reinstalling the skill.

​
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
Changes to 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-review
  • add-auth
  • fix-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: 
claude
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: 
cd docs
mint dev
Preview at http://localhost:3000 and verify:
  • Content renders correctly
  • Links work
  • Code examples are formatted properly
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:
  1. GitHub Action diffs the merge commit
  2. Passes diff to Claude (Sonnet model)
  3. Claude determines if README.md or CLAUDE.md need updates
  4. If changes are needed, creates a PR with updates
  5. 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
Then create a pull request on GitHub with:
  • 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us