Claude Code Orchestrator Kit

Professional automation and orchestration system for Claude Code

Complete toolkit with 39 AI agents, 38 skills, 25 slash commands, auto-optimized MCP, Beads issue tracking, Gastown multi-agent orchestration, ready-to-use prompts, and quality gates for building production-ready projects with Claude Code.

English | Русский

Overview
Key Innovations
Quick Start
Installation
Architecture
Agents Ecosystem
Skills Library
Slash Commands
MCP Configuration
Claude Code Settings
Prompts
Project Structure
Usage Examples
Best Practices
Gastown Setup
Contributing
License

Overview

Claude Code Orchestrator Kit transforms Claude Code from a simple assistant into an intelligent orchestration system. Instead of doing everything directly, Claude Code acts as an orchestrator that delegates complex tasks to specialized sub-agents, preserving context and enabling indefinite work sessions.

What You Get

Category	Count	Description
AI Agents	39	Specialized workers for bugs, security, testing, database, frontend, DevOps
Skills	39	Reusable utilities for validation, reporting, automation, senior expertise
Commands	25	Health checks, SpecKit, Beads, Gastown, process-logs, worktree, releases
MCP Servers	6	Auto-optimized: Context7, Sequential Thinking, Supabase, Playwright, shadcn, Serena

Key Benefits

Context Preservation: Main session stays lean (~10-15K tokens vs 50K+ in standard usage)
Specialization: Each agent is expert in its domain
Indefinite Work: Can work on project indefinitely without context exhaustion
Quality Assurance: Mandatory verification after every delegation
Senior Expertise: Skills like code-reviewer, senior-devops, senior-prompt-engineer

Key Innovations

1. Orchestrator Pattern

The Core Paradigm: Claude Code acts as orchestrator, delegating to specialized sub-agents.

┌─────────────────────────────────────────────────────────────────┐
│                     MAIN CLAUDE CODE                             │
│                   (Orchestrator Role)                            │
├─────────────────────────────────────────────────────────────────┤
│  1. GATHER CONTEXT    │  2. DELEGATE        │  3. VERIFY        │
│  - Read existing code │  - Invoke agent     │  - Read results   │
│  - Search patterns    │  - Provide context  │  - Run type-check │
│  - Check recent commits│  - Set criteria    │  - Accept/reject  │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                    SPECIALIZED AGENTS                            │
├──────────────┬──────────────┬──────────────┬───────────────────┤
│  bug-hunter  │  security-   │  database-   │  performance-     │
│  bug-fixer   │  scanner     │  architect   │  optimizer        │
│  dead-code-  │  vuln-fixer  │  api-builder │  accessibility-   │
│  hunter      │              │  supabase-   │  tester           │
│              │              │  auditor     │                   │
└──────────────┴──────────────┴──────────────┴───────────────────┘

2. Inline Skills (New Architecture)

Evolution from Orchestrators: We replaced heavy orchestrator agents with lightweight inline skills.

Old Approach	New Approach
Separate orchestrator agent per workflow	Inline skill executed directly
~1400 lines per workflow	~150 lines per skill
9+ orchestrator calls	0 orchestrator calls
~10,000+ tokens overhead	~500 tokens
Context reload each call	Single session context

Example: /health-bugs now uses bug-health-inline skill:

Detection → Validate → Fix by Priority → Verify → Repeat if needed

3. Senior-Level Skills

Professional-grade skills for complex tasks:

Skill	Expertise
`code-reviewer`	TypeScript, Python, Go, Swift, Kotlin code review
`senior-devops`	CI/CD, Docker, Kubernetes, Terraform, Cloud
`senior-prompt-engineer`	LLM optimization, RAG, agent design
`ux-researcher-designer`	User research, personas, journey mapping
`systematic-debugging`	Root cause analysis, debugging workflows

4. Auto-Optimized MCP Configuration

No manual switching required! Claude Code automatically optimizes context usage:

Single .mcp.json with all servers — no manual switching needed
Automatic deferred loading via ENABLE_TOOL_SEARCH=auto:5
85% context reduction for MCP tools (loaded on-demand via ToolSearch)
Transparent to user — just works without configuration

5. SpecKit Integration

Specification-driven development workflow with Phase 0 Planning:

Executor assignment (MAIN vs specialized agent)
Parallel agent creation via meta-agent
Atomicity: 1 Task = 1 Agent Invocation

6. Beads Issue Tracking (Optional)

Beads by Steve Yegge — git-backed issue tracker for AI agents:

Persistent tasks: Survives session restarts, tracked in git
Dependency graph: blocks, blocked-by, discovered-from
Multi-session: Work across multiple Claude sessions without losing context
8 workflow formulas: bigfeature, bugfix, hotfix, healthcheck, etc.
Initialize: Run /beads-init in your project

7. Gastown Multi-Agent Orchestration (Optional)

Gastown by Steve Yegge — multi-agent workspace manager that dispatches tasks to AI worker processes (polecats):

You (human)
  │
  ├─ /work "Fix login bug"          ← Give task via Claude Code
  │    │
  │    ├─ bd create (bead)           ← Creates task in Beads
  │    └─ gt sling PREFIX-xxx RIG   ← Dispatches to Gastown
  │         │
  │         └─ Daemon (automatic)
  │              ├─ Spawns Polecat (AI worker in isolated git worktree)
  │              ├─ Polecat: branch → implement → test → commit
  │              ├─ Refinery: merge queue → develop
  │              └─ Witness: health monitoring
  │
  ├─ /status                         ← Check progress
  └─ git push                        ← Ship changes

Key Features:

Parallel AI workers: Multiple polecats work simultaneously in isolated git worktrees
Multi-runtime: claude (default), codex, gemini — all subscription-based, no API billing
A/B testing: /work --ab "task" sends same task to 2 runtimes, compare results
Self-healing: Daemon manages Dolt DB, restarts crashed agents, monitors health
Auto-provisioning: /onboard connects any project with a single command

Included commands:

Command	Purpose
`/onboard`	Connect project to Gastown (one-time setup)
`/work "task"`	Dispatch task to AI polecat
`/status`	Show convoys, agents, pending tasks
`/upgrade`	Safely upgrade gt/bd binaries

Agent instruction templates for all runtimes are provided in .claude/templates/:

CLAUDE.md — Claude Code instructions with Gastown workflow
AGENTS.md — Codex-compatible instructions
GEMINI.md — Gemini-compatible instructions

Initialize: Run /onboard in your project directory. See Gastown Setup Guide below.

Quick Start

Option 1: npm Install

npm install -g claude-code-orchestrator-kit
cd your-project
claude-orchestrator  # Interactive setup

Option 2: Clone Repository

git clone https://github.com/maslennikov-ig/claude-code-orchestrator-kit.git
cd claude-code-orchestrator-kit

# Configure environment (optional, for Supabase)
cp .env.example .env.local
# Edit .env.local with your credentials

# Restart Claude Code - ready!

Option 3: Copy to Existing Project

# Copy orchestration system to your project
cp -r claude-code-orchestrator-kit/.claude /path/to/your/project/
cp claude-code-orchestrator-kit/.mcp.json /path/to/your/project/
cp claude-code-orchestrator-kit/CLAUDE.md /path/to/your/project/

Installation

Prerequisites

Claude Code CLI installed
Node.js 18+ (for MCP servers)
Git (for version control features)

Environment Variables

Create .env.local (git-ignored) with your credentials:

# Supabase (optional)
SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_ACCESS_TOKEN=your-token

# Sequential Thinking (optional)
SEQUENTIAL_THINKING_KEY=your-smithery-key
SEQUENTIAL_THINKING_PROFILE=your-profile

Verify Installation

# Check that .mcp.json and .claude/settings.json exist
ls -la .mcp.json .claude/settings.json

# Try a health command in Claude Code
/health-bugs

Architecture

Component Overview

┌────────────────────────────────────────────────────────────────┐
│                        CLAUDE.md                                │
│                  (Behavioral Operating System)                  │
│                                                                 │
│  Defines: Orchestration rules, delegation patterns, verification│
└────────────────────────────────────────────────────────────────┘
                              ↓
┌────────────────────────────────────────────────────────────────┐
│                         AGENTS                                  │
│            (39 specialized workers)                             │
├────────────────────────────────────────────────────────────────┤
│  health/       development/   testing/      database/          │
│  ├─bug-hunter  ├─llm-service  ├─integration ├─database-arch   │
│  ├─bug-fixer   ├─typescript   ├─performance ├─api-builder     │
│  ├─security-   ├─code-review  ├─mobile      ├─supabase-audit  │
│  ├─dead-code   ├─utility-     ├─access-     │                  │
│  └─reuse-      └─skill-build  └─ibility     │                  │
│                                                                 │
│  infrastructure/  frontend/     meta/        research/         │
│  ├─deployment     ├─nextjs-ui   ├─meta-agent ├─problem-invest  │
│  ├─qdrant         ├─fullstack   └─skill-v2   └─research-spec   │
│  └─orchestration  └─visual-fx                                  │
└────────────────────────────────────────────────────────────────┘
                              ↓
┌────────────────────────────────────────────────────────────────┐
│                         SKILLS                                  │
│            (37 reusable utilities)                              │
├────────────────────────────────────────────────────────────────┤
│  Inline Orchestration:        Senior Expertise:                 │
│  ├─bug-health-inline          ├─code-reviewer                  │
│  ├─security-health-inline     ├─senior-devops                  │
│  ├─deps-health-inline         ├─senior-prompt-engineer         │
│  ├─cleanup-health-inline      ├─ux-researcher-designer         │
│  └─reuse-health-inline        └─systematic-debugging           │
│                                                                 │
│  Utilities:                   Creative:                         │
│  ├─validate-plan-file         ├─algorithmic-art                │
│  ├─run-quality-gate           ├─canvas-design                  │
│  ├─rollback-changes           ├─theme-factory                  │
│  ├─parse-git-status           └─artifacts-builder              │
│  └─generate-report-header                                       │
└────────────────────────────────────────────────────────────────┘
                              ↓
┌────────────────────────────────────────────────────────────────┐
│                        COMMANDS                                 │
│            (21 slash commands)                                  │
├────────────────────────────────────────────────────────────────┤
│  /health-bugs      /speckit.specify    /worktree              │
│  /health-security  /speckit.plan       /push                  │
│  /health-deps      /speckit.implement  /translate-doc          │
│  /health-cleanup   /speckit.clarify    /process-logs          │
│  /health-reuse     /speckit.constitution                       │
│  /health-metrics   /speckit.taskstoissues                      │
└────────────────────────────────────────────────────────────────┘

Agents Ecosystem

39 Specialized Agents

Health (10 agents)

Agent	Purpose
`bug-hunter`	Detect bugs, categorize by priority
`bug-fixer`	Fix bugs from reports
`security-scanner`	Find security vulnerabilities
`vulnerability-fixer`	Fix security issues
`dead-code-hunter`	Detect unused code
`dead-code-remover`	Remove dead code safely
`dependency-auditor`	Audit package dependencies
`dependency-updater`	Update dependencies safely
`reuse-hunter`	Find code duplication
`reuse-fixer`	Consolidate duplicated code

Development (6 agents)

Agent	Purpose
`llm-service-specialist`	LLM integration, prompts
`typescript-types-specialist`	Type definitions, generics
`cost-calculator-specialist`	Token/API cost estimation
`utility-builder`	Build utility services
`skill-builder-v2`	Create new skills
`code-reviewer`	Comprehensive code review

Testing (6 agents)

Agent	Purpose
`integration-tester`	Database, API, async tests
`test-writer`	Write unit/contract tests
`performance-optimizer`	Core Web Vitals, PageSpeed
`mobile-responsiveness-tester`	Mobile viewport testing
`mobile-fixes-implementer`	Fix mobile issues
`accessibility-tester`	WCAG compliance

Database (3 agents)

Agent	Purpose
`database-architect`	PostgreSQL schema design
`api-builder`	tRPC routers, auth middleware
`supabase-auditor`	RLS policies, security

Infrastructure (5 agents)

Agent	Purpose
`infrastructure-specialist`	Supabase, Qdrant, Redis
`qdrant-specialist`	Vector database operations
`quality-validator-specialist`	Quality gate validation
`orchestration-logic-specialist`	Workflow state machines
`deployment-engineer`	CI/CD, Docker, DevOps

Frontend (3 agents)

Agent	Purpose
`nextjs-ui-designer`	Modern UI/UX design
`fullstack-nextjs-specialist`	Full-stack Next.js
`visual-effects-creator`	Animations, visual effects

Other (6 agents)

Agent	Purpose
`meta-agent-v3`	Create new agents
`technical-writer`	Documentation
`problem-investigator`	Deep problem analysis
`research-specialist`	Technical research
`article-writer-multi-platform`	Multi-platform content
`lead-research-assistant`	Lead qualification

Skills Library

38 Reusable Skills

Inline Orchestration (5 skills)

Execute health workflows directly without spawning orchestrator agents. All skills include Beads integration for issue tracking.

Skill	Invocation	Purpose	Version
`health-bugs`	`/health-bugs`	Bug detection & fixing with history enrichment	3.1.0
`security-health-inline`	`/health-security`	Security vulnerability scanning & fixing	3.0.0
`deps-health-inline`	`/health-deps`	Dependency audit & update	3.0.0
`cleanup-health-inline`	`/health-cleanup`	Dead code detection & removal	3.0.0
`reuse-health-inline`	`/health-reuse`	Code duplication consolidation	3.0.0

Senior Expertise (6 skills)

Professional-grade domain expertise:

Skill	Expertise
`code-reviewer`	TypeScript, Python, Go, Swift, Kotlin review
`senior-devops`	CI/CD, containers, cloud, infrastructure
`senior-prompt-engineer`	LLM optimization, RAG, agents
`ux-researcher-designer`	User research, personas
`ui-design-system`	Design tokens, components
`systematic-debugging`	Root cause analysis

Validation & Quality (6 skills)

Skill	Purpose
`validate-plan-file`	JSON schema validation
`validate-report-file`	Report completeness
`run-quality-gate`	Type-check/build/tests
`calculate-priority-score`	Bug/task prioritization
`setup-knip`	Configure dead code detection
`rollback-changes`	Restore from changes log

Reporting & Formatting (6 skills)

Skill	Purpose
`generate-report-header`	Standardized report headers
`generate-changelog`	Changelog from commits
`format-markdown-table`	Well-formatted tables
`format-commit-message`	Conventional commits
`format-todo-list`	TodoWrite-compatible lists
`render-template`	Variable substitution

Parsing & Extraction (4 skills)

Skill	Purpose
`parse-git-status`	Parse git status output
`parse-package-json`	Extract version, deps
`parse-error-logs`	Parse build/test errors
`extract-version`	Semantic version parsing

Creative & UI (6 skills)

Skill	Purpose
`algorithmic-art`	Generative art with p5.js
`canvas-design`	Visual art in PNG/PDF
`theme-factory`	Theme styling for artifacts
`artifacts-builder`	Multi-component HTML artifacts
`webapp-testing`	Playwright testing
`frontend-aesthetics`	Distinctive UI design

Automation Workflows (2 skills)

Skill	Purpose	Version
`process-logs`	Automated error log processing with Beads integration	1.8.0
`process-issues`	GitHub Issues processing with similar issue search	1.1.0

Other (4 skills)

Skill	Purpose
`git-commit-helper`	Commit message from diff
`changelog-generator`	User-facing changelogs
`content-research-writer`	Research-driven content
`lead-research-assistant`	Lead identification

Slash Commands

21 Commands

Health Monitoring (6 commands)

Command	Purpose
`/health-bugs`	Bug detection and fixing workflow
`/health-security`	Security vulnerability scanning
`/health-deps`	Dependency audit and updates
`/health-cleanup`	Dead code detection and removal
`/health-reuse`	Code duplication elimination
`/health-metrics`	Monthly ecosystem health report

Example:

/health-bugs
# Scans → Categorizes → Fixes by priority → Validates → Reports

SpecKit (9 commands)

Command	Purpose
`/speckit.analyze`	Analyze requirements
`/speckit.specify`	Generate specifications
`/speckit.clarify`	Ask clarifying questions
`/speckit.plan`	Create implementation plan
`/speckit.implement`	Execute implementation
`/speckit.checklist`	Generate QA checklist
`/speckit.tasks`	Break into tasks
`/speckit.constitution`	Define project constitution
`/speckit.taskstoissues`	Convert tasks to GitHub issues

Beads (2 commands)

Command	Purpose
`/beads-init`	Initialize Beads in project
`/speckit.tobeads`	Import tasks.md to Beads

Gastown (4 commands)

Command	Purpose
`/onboard [rig-name]`	Connect project to Gastown (one-time setup)
`/work [--agent\|--ab\|--all] "task"`	Dispatch task to AI polecat
`/status`	Show convoys, agents, pending tasks
`/upgrade [gt\|bd\|all]`	Safely upgrade Gastown/Beads binaries

Other (4 commands)

Command	Purpose
`/process-logs`	Automated error log processing and fixing
`/push [patch\|minor\|major]`	Automated release with changelog
`/worktree`	Git worktree management
`/translate-doc`	Translate documentation (EN↔RU)

MCP Configuration

Unified Auto-Optimized Setup

No more manual switching! The kit uses a single .mcp.json with automatic optimization.

How It Works

Single config file (.mcp.json) contains all MCP servers

Auto-deferred loading via .claude/settings.json:

{
  "env": { "ENABLE_TOOL_SEARCH": "auto:5" }
}

On-demand loading — Claude loads tools only when needed via ToolSearch
85% context savings compared to loading all tools upfront

Included MCP Servers

Server	Purpose	Tools
Context7	Up-to-date library documentation	`resolve-library-id`, `query-docs`
Sequential Thinking	Structured reasoning for complex tasks	`sequentialthinking`
Supabase	Database operations, migrations, RLS	Tables, SQL, migrations, edge functions
Playwright	Browser automation & testing	Screenshots, navigation, form filling
shadcn/ui	UI component library integration	Registry search, component examples
Serena	Semantic code analysis (LSP)	Symbol search, references, refactoring

Environment Variables

Set in .env.local for Supabase integration:

SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_ACCESS_TOKEN=your-token

Claude Code Settings

`.claude/settings.json`

Project-level Claude Code configuration for enhanced workflow:

{
  "plansDirectory": "./docs/plans",
  "env": {
    "ENABLE_TOOL_SEARCH": "auto:5"
  }
}

Settings Explained

Setting	Value	Purpose
`plansDirectory`	`./docs/plans`	Where Claude saves implementation plans when using Plan Mode
`ENABLE_TOOL_SEARCH`	`auto:5`	Auto-enables deferred MCP tool loading for servers with >5 tools

Benefits

Plan Mode Integration: Plans are saved to docs/plans/ for version control and review
Automatic Context Optimization: MCP tools load on-demand instead of upfront
No Manual Configuration: Works transparently — just install and use

Prompts

Ready-to-use prompts for setting up various features in your project. Copy, paste, and let Claude Code do the work.

Prompt	Description
`setup-health-workflows.md`	Health workflows with Beads integration (`/health-bugs`, `/health-security`, etc.)
`setup-error-logging.md`	Complete error logging system with DB table, logger service, auto-mute rules

Quick Start: Health Workflows

# 1. Install Beads CLI
npm install -g @anthropic/beads-cli

# 2. Initialize in your project
bd init

# 3. Run in Claude Code
/health-bugs

How to Use:

Copy the prompt content to your chat with Claude Code
Answer any questions Claude asks about your project specifics
Review the generated code before committing

See prompts/README.md for full documentation.

Project Structure

claude-code-orchestrator-kit/
├── .claude/
│   ├── agents/                 # 39 AI agents
│   │   ├── health/             # Bug, security, deps, cleanup
│   │   ├── development/        # LLM, TypeScript, utilities
│   │   ├── testing/            # Integration, performance, mobile
│   │   ├── database/           # Supabase, API, architecture
│   │   ├── infrastructure/     # Qdrant, deployment, orchestration
│   │   ├── frontend/           # Next.js, visual effects
│   │   ├── meta/               # Agent/skill creators
│   │   ├── research/           # Problem investigation
│   │   ├── documentation/      # Technical writing
│   │   ├── content/            # Article writing
│   │   └── business/           # Lead research
│   │
│   ├── skills/                 # 37 reusable skills
│   │   ├── bug-health-inline/  # Inline orchestration
│   │   ├── code-reviewer/      # Senior expertise
│   │   ├── validate-plan-file/ # Validation utilities
│   │   └── ...
│   │
│   ├── commands/               # 25 slash commands
│   │   ├── health-*.md         # Health monitoring
│   │   ├── speckit.*.md        # SpecKit workflow
│   │   ├── work.md             # Gastown: dispatch tasks
│   │   ├── status.md           # Gastown: show status
│   │   ├── upgrade.md          # Gastown: safe upgrade
│   │   ├── onboard.md          # Gastown: connect project
│   │   └── ...
│   │
│   ├── templates/              # Instruction file templates
│   │   ├── CLAUDE.md           # Claude Code template
│   │   ├── AGENTS.md           # Codex template
│   │   └── GEMINI.md           # Gemini template
│   │
│   ├── schemas/                # JSON schemas
│   └── scripts/                # Quality gate scripts
│
├── mcp/                        # Legacy MCP configs (reference only)
│   └── ...
│
├── prompts/                    # Ready-to-use setup prompts
│   ├── README.md
│   └── setup-error-logging.md
│
├── docs/                       # Documentation
│   ├── FAQ.md
│   ├── ARCHITECTURE.md
│   ├── TUTORIAL-CUSTOM-AGENTS.md
│   └── ...
│
├── .mcp.json                   # Unified MCP configuration
├── CLAUDE.md                   # Behavioral Operating System
└── package.json                # npm package config

Usage Examples

Example 1: Bug Fixing Workflow

# Run complete bug detection and fixing
/health-bugs

# What happens:
# 1. Pre-flight validation
# 2. Bug detection (bug-hunter agent)
# 3. Quality gate validation
# 4. Priority-based fixing (critical → low)
# 5. Quality gates after each priority
# 6. Verification scan
# 7. Final report

Example 2: Code Review

# Invoke code-reviewer skill
/code-reviewer

# Provides:
# - Automated code analysis
# - Best practices checking
# - Security scanning
# - Review checklist

Example 3: Release Automation

# Auto-detect version bump
/push

# Or specify type
/push minor

# Actions:
# 1. Analyze commits since last release
# 2. Bump version in package.json
# 3. Generate changelog entry
# 4. Create git commit + tag
# 5. Push to remote

Example 4: Parallel Feature Development

# Create worktrees
/worktree create feature/new-auth
/worktree create feature/new-ui

# Work in parallel
cd .worktrees/feature-new-auth
# ... changes ...

# Cleanup when done
/worktree cleanup

Best Practices

1. Use Auto-Optimized MCP

The kit automatically optimizes context usage — no configuration needed:

MCP tools load on-demand via ToolSearch
~85% context reduction compared to loading all tools upfront

2. Run Health Checks Weekly

/health-bugs      # Monday
/health-security  # Tuesday
/health-deps      # Wednesday
/health-cleanup   # Thursday
/health-metrics   # Monthly

3. Use Library-First Approach

Before writing code >20 lines, search for existing libraries:

Check npm/PyPI for packages with >1k weekly downloads
Evaluate maintenance status and types support
Use library if it covers >70% of functionality

4. Follow Orchestration Rules

GATHER CONTEXT FIRST - Read code, search patterns
DELEGATE TO SUBAGENTS - Provide complete context
VERIFY RESULTS - Never skip verification
ACCEPT/REJECT LOOP - Re-delegate if needed

5. Keep Credentials Secure

# Never commit .env.local
echo ".env.local" >> .gitignore

Gastown Setup

Prerequisites

Go 1.21+ installed (go version)

Gastown and Beads CLI installed:

go install github.com/steveyegge/gastown/cmd/gt@latest
go install github.com/steveyegge/beads/cmd/bd@latest

Gastown town initialized:
```
gt init ~/gt
```

Daemon running as systemd user service:

gt daemon enable-supervisor
systemctl --user start gastown-daemon
loginctl enable-linger $USER  # Auto-start on boot

Important: Daemon Service Customization

The default gt daemon enable-supervisor template does NOT include PATH. You must add Environment lines manually:

# Edit the service file
nano ~/.local/share/systemd/user/gastown-daemon.service

Add under [Service]:

Environment="GT_TOWN_ROOT=/home/YOUR_USER/gt"
Environment="GT_ROOT=/home/YOUR_USER/gt"
Environment="PATH=/home/YOUR_USER/go/bin:/home/YOUR_USER/.local/bin:/usr/local/bin:/usr/bin:/bin"
Environment="HOME=/home/YOUR_USER"

Then reload and restart:

systemctl --user daemon-reload
systemctl --user restart gastown-daemon

Daemon Configuration

Configure Dolt management in ~/gt/mayor/daemon.json:

{
  "heartbeat": { "enabled": true, "interval": "3m" },
  "patrols": {
    "dolt_server": {
      "enabled": true,
      "port": 3307,
      "host": "127.0.0.1",
      "user": "root",
      "data_dir": "/home/YOUR_USER/gt/.dolt-data",
      "log_file": "/home/YOUR_USER/gt/daemon/dolt-server.log",
      "auto_restart": true
    },
    "deacon": { "enabled": true, "interval": "5m", "agent": "deacon" },
    "refinery": { "agent": "refinery", "enabled": true, "interval": "5m", "rigs": [] },
    "witness": { "agent": "witness", "enabled": true, "interval": "5m", "rigs": [] }
  },
  "type": "daemon-patrol-config",
  "version": 1
}

Important: time.Duration fields like health_check_interval must be integers (nanoseconds) in Go, NOT strings like "30s". Omit them to use defaults (30 seconds).

Connect a Project

Run /onboard from your project directory in Claude Code:

/onboard

This will:

Run gt rig add <name> <path> — auto-provisions 30+ components
Update daemon.json — adds project to witness/refinery patrols
Restart daemon — picks up new configuration
Run gt doctor --fix — diagnoses and auto-fixes issues
Copy slash commands — /work, /status, /upgrade, /onboard
Copy instruction templates — CLAUDE.md, AGENTS.md, GEMINI.md

Daily Workflow

# Give task to AI agent
/work "Fix the login validation bug"

# Check progress
/status

# Use specific runtime
/work --agent codex "Refactor auth module"

# A/B test: same task to 2 agents
/work --ab "Optimize database queries"

# Find available tasks
bd ready

# Visual dashboard
gt dashboard --open

Troubleshooting

Problem	Diagnosis	Solution
Daemon not starting	`systemctl --user status gastown-daemon`	Check PATH in service file
Dolt unreachable	`gt dolt status`	Restart daemon, check `daemon.json`
Doctor failures	`gt doctor --fix --rig <name>`	Auto-fixes most issues
Polecat stuck	`gt convoy list`	`gt convoy cancel <id>`

Upgrading

/upgrade        # Upgrade both gt and bd
/upgrade gt     # Upgrade Gastown only
/upgrade bd     # Upgrade Beads only

The /upgrade command handles the full cycle: stop daemon, upgrade binaries, verify service file, check daemon.json, restart, run doctor.

Documentation

Document	Description
FAQ	Frequently asked questions
Architecture	System design diagrams
Tutorial: Custom Agents	Create your own agents
Use Cases	Real-world examples
Performance	Token optimization
Migration Guide	Add to existing projects
Commands Guide	Detailed command reference

Contributing

Adding New Agents

Create file in .claude/agents/{category}/workers/
Follow agent template structure
Add to this README

Adding New Skills

Create directory .claude/skills/{skill-name}/
Add SKILL.md following format
Add to this README

Adding MCP Servers

Add server to .mcp.json
Document in README under MCP Configuration section

Attribution

SpecKit by GitHub

Commands /speckit.* adapted from GitHub's SpecKit.

License: MIT License
Copyright: GitHub, Inc.

Beads by Steve Yegge

Beads issue tracking integration adapted from Steve Yegge's Beads.

Description: Distributed, git-backed graph issue tracker for AI agents
License: MIT License
Copyright: Steve Yegge
Commands: /beads-init, /speckit.tobeads
Templates: .beads-templates/ directory with 8 workflow formulas

Gastown by Steve Yegge

Multi-agent orchestration integration from Steve Yegge's Gastown.

Description: Multi-agent workspace manager with isolated git worktrees
License: MIT License
Copyright: Steve Yegge
Commands: /onboard, /work, /status, /upgrade
Templates: .claude/templates/ directory with instruction files for all runtimes

Acknowledgments

Built with:

Claude Code by Anthropic
Context7 by Upstash
Supabase MCP
Smithery Sequential Thinking
Playwright
shadcn/ui

Stats

39 AI Agents
39 Reusable Skills
25 Slash Commands
6 MCP Servers (auto-optimized)
3 Runtime templates (Claude, Codex, Gemini)
v1.4.20 Current Version

Author

Igor Maslennikov

GitHub: @maslennikov-ig
Website: aidevteam.ru

License

MIT License - see LICENSE file.

Star this repo if you find it useful!

Claude Code Orchestrator Kit

Table of Contents

Overview

What You Get

Key Benefits

Key Innovations

1. Orchestrator Pattern

2. Inline Skills (New Architecture)

3. Senior-Level Skills

4. Auto-Optimized MCP Configuration

5. SpecKit Integration

6. Beads Issue Tracking (Optional)

7. Gastown Multi-Agent Orchestration (Optional)

Quick Start

Option 1: npm Install

Option 2: Clone Repository

Option 3: Copy to Existing Project

Installation

Prerequisites

Environment Variables

Verify Installation

Architecture

Component Overview

Agents Ecosystem

39 Specialized Agents

Health (10 agents)

Development (6 agents)

Testing (6 agents)

Database (3 agents)

Infrastructure (5 agents)

Frontend (3 agents)

Other (6 agents)

Skills Library

38 Reusable Skills

Inline Orchestration (5 skills)

Senior Expertise (6 skills)

Validation & Quality (6 skills)

Reporting & Formatting (6 skills)

Parsing & Extraction (4 skills)

Creative & UI (6 skills)

Automation Workflows (2 skills)

Other (4 skills)

Slash Commands

21 Commands

Health Monitoring (6 commands)

SpecKit (9 commands)

Beads (2 commands)

Gastown (4 commands)

Other (4 commands)

MCP Configuration

Unified Auto-Optimized Setup

How It Works

Included MCP Servers

Environment Variables

Claude Code Settings

.claude/settings.json

Settings Explained

Benefits

Prompts

Quick Start: Health Workflows

Project Structure

Usage Examples

Example 1: Bug Fixing Workflow

Example 2: Code Review

Example 3: Release Automation

Example 4: Parallel Feature Development

Best Practices

1. Use Auto-Optimized MCP

2. Run Health Checks Weekly

3. Use Library-First Approach

4. Follow Orchestration Rules

5. Keep Credentials Secure

Gastown Setup

Prerequisites

Important: Daemon Service Customization

Daemon Configuration

Connect a Project

Daily Workflow

Troubleshooting

Upgrading

`.claude/settings.json`