Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
.claude
.claude
 
 
CLAUDE.md
CLAUDE.md
 
 
README.md
README.md
 
 

Repository files navigation

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.

Table of Contents

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:

  1. Check for pending handoffs
  2. Display handoff content
  3. 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:

  1. merge_lock counter set to 1
  2. New merges blocked
  3. Bug investigation triggered
  4. Once fixed, counter reset

Further Reading

  • Design Document: .claude/CLAWS_DESIGN.md
  • Role Definitions: .claude/roles/*.md
  • Gate Scripts: .claude/gates/*.sh

About

Claude Agent Workflow System

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages