CLAWS: Claude Agent Workflow System

A fault-tolerant workflow system for AI agent orchestration in software development. CLAWS coordinates multiple AI agents under human supervision to build software with high quality standards.

Overview

CLAWS enforces engineering discipline through structure and behavioral norms rather than hoping agents "do the right thing." The system provides:

Orchestrator-Worker Architecture: A central orchestrator (Claude) dispatches tasks to isolated specialist workers
Phase-Gated Workflows: Tasks must pass automated and manual gates before advancing
Fault Tolerance: Every state is inspectable; violations are logged for pattern analysis
Worktree Isolation: Each task gets its own git worktree for parallel development
Review Requirements: Multi-pass reviews for scope, design, and code
Session Continuity: Handoff system for maintaining context across sessions

Architecture

Human User
    │
    │  (scope approval, design collaboration, rare review)
    ▼
┌─────────────────────────────────────────────────────────────────┐
│                     ORCHESTRATOR (Claude)                       │
│                                                                 │
│  - Interprets human intent                                      │
│  - Decomposes specs into tasks (via Planning Agent)             │
│  - Assigns specialists to tasks                                 │
│  - Enforces phase gates                                         │
│  - Coordinates merges                                           │
│  - Triggers batch jobs (E2E, docs)                              │
│  - Escalates blockers to human                                  │
└─────────────────────────────────────────────────────────────────┘
    │
    │  (dispatch 1-6 concurrent task agents)
    ▼
┌─────────────────────────────────────────────────────────────────┐
│                      WORKER AGENTS                              │
│                                                                 │
│  - Specialized by domain (implementer, reviewer, etc.)          │
│  - Isolated in worktrees (cannot see each other's work)         │
│  - Cannot communicate with each other                           │
│  - Report back only on completion                               │
└─────────────────────────────────────────────────────────────────┘

Quick Start

Initialize the Database

.claude/bin/claws-init

Creates the SQLite database at .claude/claws.db with all required tables and default gate definitions.

Check System Status

.claude/bin/claws-status

Shows system health, tasks by phase, counters, and any violations.

Create Your First Task

# Create a task
.claude/bin/claws-task create TASK-001 "Implement user authentication"

# Create a worktree for it
.claude/bin/claws-worktree create TASK-001

Workflow

All tasks follow a unified workflow:

SCOPE → DESIGN → CODE → REVIEW → TEST → MERGE → VERIFY → DONE

Phase	What Happens	Gate Requirements
SCOPE	Define what to build or fix	2 scope reviews
DESIGN	Technical proposal	Proposal exists, 2 design reviews
CODE	Implementation	Tests pass, linter clean, types clean, code exists
REVIEW	Peer review	2 code reviews
TEST	Full test suite	All tests pass
MERGE	Integrate to main	Changelog entry exists
VERIFY	Final verification on main	Manual verification
DONE	Complete	-

Workflow Diagram

┌──────────────────────────────────────────────────────────────────────────┐
│                              WORKFLOW                                     │
└──────────────────────────────────────────────────────────────────────────┘

    Create Task                    Create Worktree
         │                              │
         ▼                              ▼
┌─────────────┐  2× review   ┌─────────────┐  proposal +   ┌─────────────┐
│   SCOPE     │─────────────▶│   DESIGN    │──2× review───▶│    CODE     │
│             │              │             │               │             │
│ Define what │              │  Technical  │               │  Implement  │
│ to build    │              │  proposal   │               │  + tests    │
└─────────────┘              └─────────────┘               └──────┬──────┘
                                                                  │
                                               tests, linter, types pass
                                                                  │
                                                                  ▼
┌─────────────┐   all tests  ┌─────────────┐   2× review   ┌─────────────┐
│    TEST     │◀─────────────│   REVIEW    │◀──────────────│   (ready)   │
│             │     pass     │             │               │             │
│ Full suite  │              │ Peer review │               │             │
└──────┬──────┘              └─────────────┘               └─────────────┘
       │
       │ changelog exists
       ▼
┌─────────────┐   merge to   ┌─────────────┐   verified    ┌─────────────┐
│   MERGE     │────main─────▶│   VERIFY    │──────────────▶│    DONE     │
│             │              │             │               │             │
│ Worktree    │              │ On main     │               │  Complete   │
│ cleaned up  │              │ branch      │               │             │
└─────────────┘              └─────────────┘               └─────────────┘

CLI Reference

Task Management (`claws-task`)

# Create task
.claude/bin/claws-task create <id> <title> [--spec <spec_id>]

# List tasks
.claude/bin/claws-task list [--phase <phase>] [--spec <spec_id>]

# Show task details
.claude/bin/claws-task show <id>

# Update task
.claude/bin/claws-task update <id> --specialist <role>
.claude/bin/claws-task update <id> --blocked-by <task_id>

# Transition to next phase (runs gate checks automatically)
.claude/bin/claws-task transition <id> <to_phase>

# Delete task
.claude/bin/claws-task delete <id>

Worktree Management (`claws-worktree`)

# Create isolated worktree
.claude/bin/claws-worktree create <task_id>

# List all worktrees
.claude/bin/claws-worktree list

# Merge to main and cleanup
.claude/bin/claws-worktree merge <task_id>

# Remove without merging
.claude/bin/claws-worktree remove <task_id>

Gate Checks (`claws-gate`)

# List all gates
.claude/bin/claws-gate list

# Run gate check for a transition
.claude/bin/claws-gate check <task_id> <transition>
# Example: .claude/bin/claws-gate check TASK-001 CODE-REVIEW

Reviews (`claws-review`)

# Record a review
.claude/bin/claws-review record <task_id> <artifact_type> <result> [--issues "..."]
# artifact_type: scope, design, code
# result: approved, changes_requested

# Check review status
.claude/bin/claws-review check <task_id> <artifact_type>

# List reviews for a task
.claude/bin/claws-review list <task_id>

# Clear reviews (restart cycle)
.claude/bin/claws-review clear <task_id> [<artifact_type>]

Worker Prompts (`claws-worker`)

# Get role prompt
.claude/bin/claws-worker prompt <role>

# Get full context (role + task info)
.claude/bin/claws-worker context <task_id> <role>

# List available roles
.claude/bin/claws-worker roles

System Status (`claws-status`)

.claude/bin/claws-status              # Full overview
.claude/bin/claws-status health       # Health check
.claude/bin/claws-status tasks        # Tasks by phase
.claude/bin/claws-status gates        # Gate definitions
.claude/bin/claws-status counters     # System counters
.claude/bin/claws-status violations   # Recent violations

Counters (`claws-counter`)

.claude/bin/claws-counter list
.claude/bin/claws-counter get <name>
.claude/bin/claws-counter set <name> <value>
.claude/bin/claws-counter reset <name>

Backups (`claws-backup`)

.claude/bin/claws-backup create [name]
.claude/bin/claws-backup auto          # Rotating backup
.claude/bin/claws-backup list
.claude/bin/claws-backup restore <name>

Specialist Roles

CLAWS uses 7 parameterized specialist roles:

Role	Description
`planning`	Decompose specs into sized tasks
`architect`	Design and technical proposals
`implementer`	All implementation (backend, frontend, infra, ai-dl)
`reviewer`	All reviews (scope, design, code)
`bug-investigator`	Root cause analysis with differential diagnosis
`validator`	QA, E2E testing, documentation, verification

Each role has a detailed prompt in .claude/roles/. All roles inherit behavioral norms from .claude/roles/_base.md.

Gate System

Gates are automated checks defined in the database. Each transition has specific requirements:

Transition	Gates
SCOPE → DESIGN	2 scope reviews
DESIGN → CODE	Proposal exists, 2 design reviews
CODE → REVIEW	Tests pass, linter clean, types clean, code exists
REVIEW → TEST	2 code reviews
TEST → MERGE	Full test suite passes
MERGE → VERIFY	Changelog entry exists
VERIFY → DONE	Manual verification

Gates are stored in the gates table and can be customized per project:

SELECT transition, gate_type, gate_value, description FROM gates;

Gate Types

Type	Description
`script`	Run a shell script (e.g., `check_tests.sh`)
`reviews`	Require N approved reviews (format: `artifact:count`)
`file_exists`	Check file exists (supports globs)
`code_exists`	Check for code changes in src/tests
`manual`	Manual verification required

Session Management

Ending a Session

Use the /wrapup command:

/wrapup           # Archive session
/wrapup continue  # Handoff for next session

Session CLI (`claws-session`)

# Save session handoff (archived, no continuation)
cat <<'EOF' | .claude/bin/claws-session wrapup
# Session Handoff
...
EOF

# Save with continuation flag
cat <<'EOF' | .claude/bin/claws-session wrapup --continue
# Session Handoff
...
EOF

# Check for pending handoff
.claude/bin/claws-session pending

# Mark handoff as resumed
.claude/bin/claws-session resume

Starting a New Session

Run .claude/bin/claws-status to:

Check for pending handoffs
Display handoff content
Show current system state

Directory Structure

.claude/
├── bin/                    # CLI scripts
│   ├── claws-init
│   ├── claws-status
│   ├── claws-task
│   ├── claws-worktree
│   ├── claws-gate
│   ├── claws-worker
│   ├── claws-review
│   ├── claws-counter
│   ├── claws-backup
│   ├── claws-session
│   └── claws-common.sh
├── gates/                  # Gate check scripts
│   ├── check_tests.sh      # Python + Node.js
│   ├── check_linter.sh
│   ├── check_types.sh
│   ├── check_todos.sh
│   └── check_orphans.sh
├── roles/                  # Worker role definitions
│   ├── _base.md            # Shared behavioral norms
│   ├── planning.md
│   ├── architect.md
│   ├── implementer.md
│   ├── reviewer.md
│   ├── bug-investigator.md
│   └── validator.md
├── templates/
│   └── bug-report.md
├── commands/
│   └── wrapup.md
├── backups/
├── claws.db
└── CLAWS_DESIGN.md

Core Principles

Fault Tolerance

Every state is inspectable (database, worktrees, artifacts)
Phase gates are the enforcement mechanism
Violations are logged for pattern analysis

Main Branch is Sacred

If main is broken, no new merges until fixed
Merge lock activates when E2E fails

Workers Own Their Failures

If a gate fails, the worker fixes it
No passing broken work to the next phase

System States

    HEALTHY                    DEGRADED
       │                          │
       │  E2E fails               │  E2E passes
       │                          │
       ▼                          ▼
  ┌─────────┐              ┌──────────┐
  │ Normal  │◀────────────▶│  Merge   │
  │  flow   │              │  locked  │
  └─────────┘              └──────────┘

When E2E fails:

merge_lock counter set to 1
New merges blocked
Bug investigation triggered
Once fixed, counter reset

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.claude		.claude
CLAUDE.md		CLAUDE.md
README.md		README.md

Navigation Menu

Repository files navigation

CLAWS: Claude Agent Workflow System

Table of Contents

Overview

Architecture

Quick Start

Initialize the Database

Check System Status

Create Your First Task

Workflow

Workflow Diagram

CLI Reference

Task Management (`claws-task`)

Worktree Management (`claws-worktree`)

Gate Checks (`claws-gate`)

Reviews (`claws-review`)

Worker Prompts (`claws-worker`)

System Status (`claws-status`)

Counters (`claws-counter`)

Backups (`claws-backup`)

Specialist Roles

Gate System

Gate Types

Session Management

Ending a Session

Session CLI (`claws-session`)

Starting a New Session

Directory Structure

Core Principles

Fault Tolerance

Main Branch is Sacred

Workers Own Their Failures

System States

Further Reading

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

CLAWS: Claude Agent Workflow System

Table of Contents

Overview

Architecture

Quick Start

Initialize the Database

Check System Status

Create Your First Task

Workflow

Workflow Diagram

CLI Reference

Task Management (claws-task)

Worktree Management (claws-worktree)

Gate Checks (claws-gate)

Reviews (claws-review)

Worker Prompts (claws-worker)

System Status (claws-status)

Counters (claws-counter)

Backups (claws-backup)

Specialist Roles

Gate System

Gate Types

Session Management

Ending a Session

Session CLI (claws-session)

Starting a New Session

Directory Structure

Core Principles

Fault Tolerance

Main Branch is Sacred

Workers Own Their Failures

System States

Further Reading

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Task Management (`claws-task`)

Worktree Management (`claws-worktree`)

Gate Checks (`claws-gate`)

Reviews (`claws-review`)

Worker Prompts (`claws-worker`)

System Status (`claws-status`)

Counters (`claws-counter`)

Backups (`claws-backup`)

Session CLI (`claws-session`)