Skip to content

Development Mode

Enter developmental agent mode — orient on architecture, key locations, and dev workflow for modifying work-buddy itself

When to use

When the user invokes /wb-dev, asks to build something in work-buddy, or needs to add/fix a capability, workflow, service, or dashboard feature

Slash command: /wb-dev

  • mcp_registry_reload

Directions

You are a developmental agent, not an operational one. Your job is to modify the work-buddy codebase itself — add capabilities, fix bugs, improve workflows, extend services. You are not running morning routines or triaging tasks.

Step 1: Orient on architecture

Before writing code, understand the three core constructs and their design tenets:

  • Capabilities — atomic Python functions registered in registry.py. Single operation, reusable from anywhere. Invoked via wb_run("name", params), executes immediately.
  • Workflows — DAG definitions in knowledge/store/workflows.json as WorkflowUnit entries. Multi-step procedures requiring ordering, user decisions, or state threading. Started via wb_run("name"), advanced via wb_advance(run_id, result).
  • Auto-run steps — workflow steps marked auto_run in workflows.json. The conductor executes these transparently — the agent never sees them. Use for deterministic code (config loading, data formatting) that needs no agent reasoning.

Decision heuristic: Can you write a unit test with a fixed expected output? → Capability. Does the "correct" output depend on interpretation, user input, or synthesis? → Workflow step. Is the step itself deterministic with no side effects? → Auto-run step.

For gateway design tenets (Progressive Disclosure, Just-in-Time Retrieval, etc.), see the dev/design-tenets knowledge unit.

For the MCP import discipline (asyncio deadlock hazard), see architecture/mcp-import-discipline.

Step 2: Key locations

MCP capability registry

work_buddy/mcp_server/registry.py — all MCP capabilities are registered here. Each category has a builder function (_task_capabilities(), _sidecar_capabilities(), etc.) that returns a list of Capability dataclass instances.

To add a capability: 1. Write the function inside the relevant _*_capabilities() builder 2. Add a Capability(name=..., callable=..., ...) to the returned list 3. Reload without restart: mcp__work-buddy__wb_run("mcp_registry_reload") 4. Verify: mcp__work-buddy__wb_search("your_capability")

Workflows

knowledge/store/workflows.json — each WorkflowUnit contains the full DAG structure (steps, dependencies, auto_run specs, step instructions). The conductor (work_buddy/mcp_server/conductor.py) reads these at runtime via _discover_workflows_from_store().

To add a workflow: 1. Add a WorkflowUnit entry to knowledge/store/workflows.json with steps, dependencies, and step instructions 2. Create a matching slash command in .claude/commands/wb-<name>.md 3. Create a behavioral directions unit in the knowledge store (loaded by the slash command) 4. Update the capability/workflow table in CLAUDE.md

Slash commands

.claude/commands/wb-*.md — all 34 are thin launchers that load behavioral directions from the knowledge store via agent_docs. Behavioral guidance goes in the knowledge store directions unit, not in workflow step instructions (see the priming hazard note under dev/design-tenets).

Sidecar services

Each service follows the pattern: work_buddy/<service>/service.py with Flask app, /health endpoint, and main() entry point. Configured in config.yaml under sidecar.services.

To add a service: 1. Create work_buddy/<name>/ with __init__.py, __main__.py, service.py 2. Add entry to config.yaml under sidecar.services 3. Service must have GET /health returning {"status": "ok"} 4. Sidecar auto-starts, health-checks, and restarts it

Dashboard

work_buddy/dashboard/ — web UI on port 5127. See work_buddy/dashboard/README.md for the tab-adding pattern.

Step 3: Dev workflow

Running Python

powershell.exe -Command "cd <vault-root>\repos\work-buddy; conda activate work-buddy; <command>"

Testing capabilities

`mcp__work-buddy__wb_run("mcp_registry_reload")`   # pick up code changes
`mcp__work-buddy__wb_search("your_query")`          # verify discovery
`mcp__work-buddy__wb_run("capability_name", {...})`  # test execution

Restarting services

`mcp__work-buddy__wb_run("service_restart", {"service": "dashboard"})`
Or by port in PowerShell: 
Get-NetTCPConnection -LocalPort <port> | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }

Dependencies

Never use pip install. Use Poetry: - Production: poetry add <package> - Temporary/testing: poetry add --group temp <package>

Step 4: Orient on focus area

If an argument was provided, read the relevant subsystem README and code. If blank, you're oriented — ask the user what to build.

Key subsystem READMEs: - work_buddy/dashboard/README.md - work_buddy/sidecar/README.md - work_buddy/messaging/README.md - work_buddy/obsidian/tasks/README.md - work_buddy/memory/README.md - work_buddy/notifications/README.md - work_buddy/telegram/README.md

What NOT to do

  • Don't run operational workflows — you're here to build, not to operate
  • Don't guess at imports — mcp__work-buddy__wb_search() first, then check the code
  • Don't add features without slash commands — every user-facing capability needs one
  • Don't forget documentation — update knowledge store units, section in CLAUDE.md, command table
  • Don't commit unrelated files — stage only what you changed