dotclaude

A multi-agent development workflow system for Claude Code.

Overview

This repository provides a structured workflow for software development using specialized AI agents. The system enables:

• Systematic project planning and specification
• Parallel development with git worktrees
• Automated code validation
• Language-specific coding standards
• Orchestrator-managed workflow from init to merge

For the full project structure, see Architecture. For model selection criteria across agents, see the Agent Model Selection Guide — criteria for assigning Claude models to agents.

Getting Started

Install

Option 1: Plugin Marketplace (Recommended)

Install dotclaude via Claude Code's plugin marketplace:

# Add the marketplace repository (first time only)
/plugin marketplace add https://github.com/U-lis/dotclaude

# Install the plugin
/plugin install dotclaude

Option 2: Manual Installation

For direct control or customization, clone and copy manually:

git clone https://github.com/U-lis/dotclaude.git
cp -r dotclaude/.claude your-project/

Note: For updates, use /plugin update dotclaude (plugin installation) or re-clone and copy (manual installation). Restart Claude Code after updating to apply changes.

Optional: GitHub CLI

The /dotclaude:pr command requires GitHub CLI (gh).

• Install: brew install gh (macOS) or see installation guide
• Authenticate: gh auth login

Configure

Configure dotclaude settings for your project:

/dotclaude:configure

See the Configuration section below for available settings and file locations.

Start Your First Task

# In Claude Code session
/dotclaude:start-new

# Orchestrator takes over:
# 1. Asks work type (Feature/Bugfix/Refactor/GitHub Issue)
# 2. Gathers requirements via step-by-step questions
#    - If GitHub Issue: parses issue URL, auto-detects type, pre-fills fields
#      and skips questions already answered in the issue body
# 3. Asks target version (auto-filled from milestone if GitHub Issue)
# 4. Creates and reviews SPEC with user
# 5. Asks execution scope (Design only / Design+Code / Design+Code+Docs)
# 6. Executes selected scope
# 7. Asks post-completion integration (Direct Merge or Create PR)
# 8. Returns final summary

# Reuse current conversation context as initialization input (skip redundant Q&A):
/dotclaude:start-new --prefill

# Combine prefill with a GitHub issue URL (asks how to merge the two sources):
/dotclaude:start-new --prefill https://github.com/owner/repo/issues/123

# After merge, create version tag (verifies version consistency, pushes automatically):
/dotclaude:tagging
# Or specify version explicitly:
/dotclaude:tagging 0.3.0

Note: --prefill automatically detects the work type from the conversation, extracts pre-filled answers, and skips matching questions. Sensitive data (API keys, passwords, JWT tokens, etc.) is filtered before being passed to init commands.

Manual Execution (Bypass Orchestrator)

Individual skills can be invoked directly for debugging or partial work:

/dotclaude:design           # Create implementation plan
/dotclaude:validate-spec    # Validate document consistency
/dotclaude:code 1           # Implement Phase 1
/dotclaude:code all         # Implement all phases
/dotclaude:update-docs      # Update documentation
/dotclaude:merge             # Merge to base branch
/dotclaude:tagging          # Create version tag (with push + version checks)
/dotclaude:tagging 0.3.0   # Create tag for specific version
/dotclaude:purge            # Clean up merged branches and worktrees
/dotclaude:purge 0.3.0     # Clean up using specific version as deployment boundary

Configuration

dotclaude supports both global and per-project configuration.

Configuration Files

Scope	Location	Description
Global	~/.claude/dotclaude-config.json	Applies to all projects
Local	<project_root>/.claude/dotclaude-config.json	Project-specific overrides

Configuration merge order: Defaults < Global < Local

Configuration Command

/dotclaude:configure

Interactive workflow to edit settings at global or local scope. Basic settings (Language, Working Directory, Base Branch) are presented as a multi-question batch for faster configuration. Version Files uses a separate interactive workflow. Changes take effect immediately.

Available Settings

Setting	Type	Default	Description
language	string	en_US	Language for agent conversations and user-facing text. Set via SessionStart hook. Documents remain in English.
working_directory	string	.dc_workspace	Directory for work files (relative to project root)
base_branch	string	main	Default base branch for git operations
version_files	array	[]	Version files for tagging consistency check. Empty = auto-detect. See Version Files.

Version Files

When version_files is empty (default), /dotclaude:tagging auto-detects common version files in the project (e.g., package.json, pyproject.toml, Cargo.toml, .claude-plugin/plugin.json). To override, configure explicit {path, pattern} entries where pattern is a regex with a capture group for the version string. CHANGELOG.md is always included regardless of configuration. Use /dotclaude:configure (Setting 4) to manage version files interactively -- the "Auto-detect and suggest" option scans the project for all 7 known version file types, shows their status, and lets you add or remove entries in one step.

Commands & Core Workflow

Skills (Commands)

All dotclaude skills are prefixed with dotclaude: namespace:

Command	Description
/dotclaude:configure	Interactive configuration management
/dotclaude:start-new	Entry point - calls orchestrator for full workflow. Supports --prefill to reuse prior conversation context and a GitHub issue URL argument
/dotclaude:design	Transform SPEC into implementation plan
/dotclaude:validate-spec	Validate document consistency (optional)
/dotclaude:code [phase]	Execute coding for specified phase
/dotclaude:code all	Execute all phases automatically
/dotclaude:merge	Merge current branch to base branch
/dotclaude:pr	Create GitHub Pull Request with structured body (Summary, Changes, Test plan) from design docs or git history
/dotclaude:tagging [version]	Create version tag with push enforcement and version consistency checks
/dotclaude:update-docs	Update documentation (CHANGELOG, README)
/dotclaude:purge [version]	Clean up merged branches and orphaned worktrees

Orchestrator

The orchestrator workflow is integrated into /dotclaude:start-new command (commands/start-new.md):

• Manages entire workflow from init to merge
• Coordinates subagents via Task tool
• Enables parallel execution for parallel phases
• Tracks state for resumability

Appendix

Agents

Agent	Role
Designer	Technical architecture and phase decomposition
TechnicalWriter	Structured documentation
spec-validator	Document consistency validation
code-validator	Code quality + plan verification
Coders	Language-specific implementation

Agents have YAML frontmatter (name, description) and can be invoked directly via dotclaude:{agent-name} pattern.

Note: Orchestrator workflow is now integrated into /dotclaude:start-new command.

Document Types

Simple Tasks (1-2 phases)

{working_directory}/{SUBJECT}.md

Directory Naming Convention

Documentation directories use date-prefixed names for chronological sorting:

{working_directory}/{yyyy_mm_dd}-{subject}/

• {yyyy_mm_dd}: Local date when directory is created (e.g., 2026_02_25)
• {subject}: Work keyword (e.g., auth, api-cleanup)
• Combined as {doc_dir} variable (e.g., 2026_02_25-auth)

This variable is stored in SPEC.md metadata as doc_dir and used by downstream commands for path resolution.

Note: {subject} continues to be used for branch names and commit messages.

Complex Tasks (3+ phases)

{working_directory}/{doc_dir}/               # Example: claude_works/2026_02_25-auth/
├── SPEC.md                      # Requirements (What)
├── GLOBAL.md                    # Architecture, phase overview
├── PHASE_1_PLAN_{keyword}.md    # Implementation plan
├── PHASE_1_TEST.md              # Test cases
└── ...

Parallel Phases

├── PHASE_3A_PLAN_{keyword}.md   # Parallel work A
├── PHASE_3B_PLAN_{keyword}.md   # Parallel work B
├── PHASE_3.5_PLAN_MERGE.md      # Merge phase (required)

Phase Naming Convention

Type	Pattern	Example
Sequential	PHASE_{k}	PHASE_1, PHASE_2
Parallel	PHASE_{k}{A|B|C}	PHASE_3A, PHASE_3B
Merge	PHASE_{k}.5	PHASE_3.5

13-Step Workflow

Step	Phase	Description
1	Init	Work type selection
2	Init	Load init instructions (questions, analysis, target version, branch, SPEC)
3	Init	SPEC review
4	Init	SPEC commit
5	Init	Scope selection
6	Design	Designer analysis
7	Design	Document creation via TechnicalWriter
8	Design	Design commit
9	Code	Phase list parsing
10	Code	Phase execution (sequential/parallel)
11	Docs	Documentation update
12	Integration	Post-completion integration (Direct Merge or Create PR)
13	Final	Summary return

License

MIT