SAW — SAFe Agentic Workflow

AI Agent Harness for Multi-Agent Team Workflows

A Production-Tested Three-Layer Architecture for Coordinated AI Teams

Template Repository - Click "Use this template" above to create your own AI agent harness. After cloning, run bash scripts/setup-template.sh to customize for your project. See TEMPLATE_SETUP.md for details.

What This Is

A production-tested AI agent harness for teams that want structured AI workflows.

Multi-provider support: Works with Claude Code (Anthropic), Gemini CLI (Google), Codex CLI (OpenAI), and Cursor IDE (Anysphere).

Built on SAFe methodology (Scaled Agile Framework), adapted for AI agent teams. Works for any team with repeatable processes: Software, Marketing, Research, Legal, Operations.

Includes:

• 18 Model-Invoked Skills - Domain expertise that loads automatically (Skills 2.0 frontmatter)
• 24 Slash Commands - Workflow automation for common tasks
• 11 SAFe Agent Profiles - Specialized roles with clear boundaries
• Three-Layer Architecture - Hooks → Commands → Skills
• Agent Teams - Multi-agent orchestration with SAFe quality gates (experimental)
• Dark Factory - Persistent autonomous agent teams via tmux on remote servers (guide)

Origin: 5 months production use, 169 issues, 2,193 commits. Implements patterns from 6 Anthropic engineering papers and SAFe methodology.

Quick Start (30 seconds)

Claude Code (Anthropic)

# Copy harness to your project
cp -r .claude/ /your-project/.claude/

# Customize placeholders
edit .claude/SETUP.md  # Replace {{TICKET_PREFIX}}, {{PROJECT_NAME}}

# Start working
/start-work TICKET-123

Gemini CLI (Google)

# Copy harness to your project
cp -r .gemini/ /your-project/.gemini/

# Install Gemini CLI (if needed)
npm install -g @google/gemini-cli

# Authenticate
export GEMINI_API_KEY="your-api-key"

# Start working
/workflow:start-work TICKET-123

Codex CLI (OpenAI)

# Copy harness to your project
cp -r .codex/ /your-project/.codex/
cp -r .agents/ /your-project/.agents/

# Install Codex CLI (if needed)
npm install -g @openai/codex

# Authenticate
export OPENAI_API_KEY="your-api-key"

# Start working (natural language, no slash commands)
codex

Cursor IDE (Anysphere)

# Copy rules to your project
cp -r .cursor/ /your-project/.cursor/

# Open in Cursor
cursor /your-project

# Rules activate automatically based on file context
# Use @rule-name to invoke agent roles manually

That's it. Your AI assistant now has your team's workflow patterns built in.

Keeping Your Harness Updated

Already using the harness and a new version is out? You have two paths:

Automated (multi-domain, manifest-based):

# Initialize sync metadata (first time only)
./scripts/sync-claude-harness.sh init
./scripts/sync-claude-harness.sh manifest init --yes

# Preview and apply (syncs all domains in your manifest's sync_scope)
./scripts/sync-claude-harness.sh sync --version v2.10.0 --dry-run
./scripts/sync-claude-harness.sh sync --version v2.10.0

# Sync specific domains only
./scripts/sync-claude-harness.sh sync --version v2.10.0 --scope .claude,.gemini

Manual (full release, all providers):

git remote add harness https://github.com/bybren-llc/safe-agentic-workflow.git
git fetch harness main --tags
git diff v2.9.0..v2.10.0 --stat              # See what changed
git checkout harness/main -- .codex/agents/   # Cherry-pick what you need
bash scripts/setup-template.sh                # Re-apply your placeholders

The sync script protects your customizations via a manifest (required since v2.10.0). It won't overwrite files you've marked as protected. See the Harness Sync Guide for the full reference and Upgrade Guide for rollback options.

The Three-Layer Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                      Claude Code Harness                              │
├──────────────────────────────────────────────────────────────────────┤
│  LAYER 1: HOOKS     │ Automatic guardrails (format checks, blockers) │
│  LAYER 2: COMMANDS  │ User-invoked workflows (/start-work, /pre-pr)  │
│  LAYER 3: SKILLS    │ Model-invoked expertise (pattern discovery)    │
└──────────────────────────────────────────────────────────────────────┘

Philosophy: Process as service, not control. Everything exists to reduce cognitive load on already-solved problems.

Choose Your Path

Getting Started

1. Run bash scripts/setup-template.sh to customize placeholders
2. Read the Getting Started Guide for the full walkthrough
3. Run /start-work on your first ticket

Adopting into an existing repo? See the Workspace Adoption Guide. Upgrading from a previous version? See Keeping the Harness Updated. Syncing your fork with upstream? See the Harness Sync Guide.

Key Commands

Full Command Reference

Workflow (8): /start-work, /pre-pr, /release, /end-work, /check-workflow, /update-docs, /retro, /sync-linear

Local Operations (3): /local-sync, /local-deploy, /quick-fix

Remote Operations (5): /remote-status, /remote-deploy, /remote-health, /remote-logs, /remote-rollback

Complete Setup Guide

Research Foundation

This harness implements patterns from 6 Anthropic engineering papers (see below).

See docs/whitepapers/ for methodology deep-dives and comparative analysis.

Adoption Requirements

• At least one supported AI tool: Claude Code, Gemini CLI, Codex CLI, or Cursor IDE
• Git repository
• Team buy-in for structured workflows

Why Teams Choose SAW

• Structured autonomy: AI agents work within clear boundaries and quality gates
• Evidence-based delivery: Every deliverable requires verifiable evidence, not "trust me"
• Stop-the-line authority: Any agent can halt work for quality or security concerns
• Multi-provider flexibility: Same workflow across Claude Code, Gemini CLI, Codex CLI, and Cursor IDE

Known Limitations

• Claude Code has the deepest integration; Gemini CLI, Codex CLI, and Cursor IDE support is newer
• Non-SWE domain adaptations (marketing, research) are documented but not yet validated in production

Gemini CLI Integration

Gemini CLI Unique Features

Gemini CLI offers capabilities that complement Claude Code: