AI Assistant Integration

Teach your AI coding assistant to coordinate work through the task graph.

How it works

Workgraph includes a skill definition that teaches AI assistants to use it as a coordinator. The skill teaches agents to:

  • Run wg quickstart at session start to orient themselves
  • Act as a coordinator — start the service, define tasks, monitor progress
  • Let the service handle claiming and spawning, not do it manually
  • Decompose complex goals into task graphs with dependencies

Claude Code

Install the skill from the workgraph directory:

wg skill install     # installs to ~/.claude/skills/

The skill has YAML frontmatter so Claude auto-detects when to use it. You can also invoke it explicitly with /wg.

Add this to your project's CLAUDE.md (or ~/.claude/CLAUDE.md for global):

Use workgraph for task management.

At the start of each session, run `wg quickstart` to orient yourself.
Use `wg service start` to dispatch work — do not manually claim tasks.

You can also discover and inspect available skills:

wg skill list              # list available skills
wg skill find <query>      # search skills by keyword
wg skill task <task-id>    # show skills relevant to a task

OpenCode, Codex, and other agents

Add the core instruction to your agent's system prompt or AGENTS.md:

## Task Management

Use workgraph (`wg`) for task coordination.
Run `wg quickstart` to orient yourself.

As a top-level agent, use service mode:
- `wg service start` to start the coordinator
- `wg add "Task" --after dep` to define work
- `wg list` / `wg agents` to monitor progress

The service automatically spawns agents and claims tasks.
See `wg --help` for all commands.

What the skill teaches

The skill turns an AI assistant into a thin orchestrator. The orchestrating agent doesn't write code itself — it creates tasks with descriptions, dependencies, and validation criteria, then delegates execution to the service.

The orchestrator's job is limited to:

  • Conversation with the user
  • Inspection — wg show, wg viz, wg list, wg status
  • Task creation — wg add with descriptions, dependencies, and context
  • Monitoring — wg agents, wg service status, wg watch

Everything else — code, research, documentation — gets dispatched through wg add and wg service start.

Task creation from agents

When an AI agent creates tasks, it should include validation criteria so the service can verify the work: 

wg add "Implement feature X" --after design \
  --verify "cargo test test_feature_x passes" \
  -d "## Description
Implement the feature as designed.

## Validation
- [ ] Failing test written first (TDD)
- [ ] Implementation makes the test pass
- [ ] cargo build + cargo test pass"

The --verify flag attaches a machine-checkable gate. The description's Validation section provides human-readable criteria for the executing agent.

Multi-agent coordination

With the service running, the orchestrating agent can fan out parallel work: 

# Fan out
wg add "Refactor auth" --skill rust
wg add "Update tests" --after refactor-auth --skill testing
wg add "Update docs" --after refactor-auth --skill docs

# Start the service — it dispatches agents in parallel
wg service start --max-agents 4

# The orchestrating agent monitors
wg agents
wg list

Each spawned agent works in its own git worktree, so parallel agents don't conflict. The coordinator handles worktree setup and cleanup.