safe-agentic-workflow

SAW — SAFe Agentic Workflow

AI Agent Harness for Multi-Agent Team Workflows

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

Supported AI Providers

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:

• 20 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)
• Knowledge Vault - Evidence-verified knowledge base with a drift-detecting validator (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 across all provider files ({{TICKET_PREFIX}}, {{PROJECT_NAME}},
# and the rest) in one pass:
bash scripts/setup-template.sh

# 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.11.1 --dry-run
./scripts/sync-claude-harness.sh sync --version v2.11.1

# Sync specific domains only
./scripts/sync-claude-harness.sh sync --version v2.11.1 --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.10.0..v2.11.1 --stat             # See what changed
git checkout harness/main -- .codex/agents/   # Cherry-pick what you need
bash scripts/sync-claude-harness.sh --dry-run # Preview, then drop --dry-run to apply

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

For Practitioners - I want to use this today

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. Planning a multi-issue program? See the SAFe x AI-DLC Methodology. Building a knowledge base? See the Knowledge Vault.

Key Commands

Command	Purpose
/start-work	Begin ticket with proper workflow
/pre-pr	Validate before pull request
/end-work	Complete session cleanly
/check-workflow	Quick status check

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

For Researchers - I want to understand the methodology

Research Foundation

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

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

For Leaders - I want to understand adoption

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

Why Gemini CLI? - Unique capabilities and when to use it

Gemini CLI Unique Features

Gemini CLI offers capabilities that complement Claude Code:

Feature	Gemini CLI	Claude Code
Shell Injection	!{command} - Execute shell, inject output into prompt	Via Bash tool only
File Injection	@{file} - Inject file contents into prompts	Via Read tool only
Built-in Sandbox	Google Cloud sandboxing	MCP sandboxing
Model Options	Gemini 3 Flash, Gemini 3.1 Pro Preview	Claude Opus, Sonnet, Haiku
Command Format	TOML	YAML + Markdown
Namespaced Commands	/workflow:start-work	/start-work
Hooks	settings.json hooks section	hooks-config.json
MCP Servers	settings.json mcpServers	settings.local.json
Hook Migration	gemini hooks migrate --from-claude	N/A
Plan Mode	/plan command, plan-then-execute	N/A
Policy Engine	YAML policies, seatbelt profiles	N/A
Browser Agent	Built-in experimental agent	MCP (claude-in-chrome)
Extensions	Bundled skill/MCP/command packages	N/A
Checkpointing	/restore session recovery	N/A
Audio/Video	Native multimodal (Gemini 3+)	N/A

When to Use Gemini CLI

Choose Gemini CLI when you need:

• Shell command output directly in prompts (!{git log --oneline -5})
• File contents injected into context (@{package.json})
• Plan mode for complex multi-step tasks (/plan)
• Audio/video transcription and analysis (Gemini 3+ multimodal)
• Policy engine for fine-grained tool control
• Google Cloud integration and Gemini model family access

Choose Claude Code when you need:

• Agent subprocesses with tool restrictions
• Claude model family access