- 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.
Overview
- 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.
README
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.shto 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
Gemini CLI Integration
Implementing Anthropic’s Research
This harness directly implements patterns from Anthropic’s engineering papers:
| Paper | What We Implement |
|---|---|
| Building Effective Agents | 11-agent team structure |
| Effective Harnesses | Three-layer architecture |
| Agent Skills | 20 model-invoked skills |
| Skills Announcement | Skills 2.0 frontmatter, trigger patterns |
| Code Execution with MCP | Tool restrictions per role |
“The best harness is one you forget exists.” — Agent Perspective
SAFe Foundation
Program Cadence: SAFe x AI-DLC
SAFe gives this harness its structure. But SAFe’s cadence assumes human squads on week-long sprints, and agent teams do not move at that speed — a team of specialized agents can elaborate, build, and verify a unit of work in hours.
So the harness also ships the SAFe x AI-DLC fusion: SAFe keeps the hierarchy, WSJF, role boundaries, and Definition of Done; AWS’s AI-Driven Development Life Cycle supplies the cadence and the human checkpoint. In a program that adopts the fusion, the Bolt takes the sprint’s place. Adoption is per-program; the standard sprint path stays valid.
Inside such a program, each concept below stands in for its SAFe counterpart:
| Concept | Stands in for | Definition |
|---|---|---|
| Bolt | The sprint | An hours-to-days swarm with an entry gate and a hard exit. Exits on evidence, not a date. |
| Unit of Work | The Feature | One coherent outcome. A project in the tracker. |
| Mob Elaboration | Sprint planning | Decompose, list unknowns, ask questions — before writing any code. |
| The loop | The stand-up | AI plans → AI asks → human validates business context → AI executes. |
The human validation step is not optional. Agents own the build; humans own the judgment — secrets, security policy, branch protection, risk thresholds, and signing the Definition of Done always route to a human with options and a recommendation.
Using It
| Resource | Purpose |
|---|---|
| Methodology guide | Read this first — vocabulary, worked example, when not to use a Bolt |
safe-ai-dlc skill |
The method encoded for agents (Claude, Gemini, portable; Cursor as a rule) |
| Program template | Scaffolding for a new program document |
linear-sop skill |
Program structure: initiative → project → milestone → issue |
Use it when work spans many issues and needs cadence — turning an audit, epic, or initiative into
an executable program. For a single ticket, the standard safe-workflow path is correct. And if the
problem space is still unclear, run a spike instead: forcing an ambiguous epic into one Bolt just
relocates the ambiguity into the code.
Knowledge Vault
Agent teams need a shared map of the system, and a map nobody can prove is current will quietly
become wrong. The knowledge-vault/ subsystem is an evidence-verified knowledge base: every
concept records the commit its claims were checked against, so staleness is something you
compute, not something you feel.
Built on Open Knowledge Format v0.1 (Google, Apache-2.0), which gives portability. This harness adds the rigor layer that gives trust: a strict frontmatter contract, a zero-dependency validator, an anti-hallucination link rule, and a drift mechanism.
In the project this method came from, an independent architecture audit called the vault “the single strongest KT asset in the repo” and told new developers to trust it over the project’s own canonical context file — because the vault’s claims were verified against a SHA and the canonical file’s had silently drifted.
Run It
| Prompt | Who it is for |
|---|---|
| BUILD-PROMPT.md | Every adopter — the generic multi-agent build prompt. Fill in your project, taxonomy, and watch-list, then run it. |
| SAW-VAULT-BUILD.md | This repo’s maintainers — pre-scoped to {{PROJECT_SHORT}} and runnable as-is, with a ready-to-file ticket breakdown. |
# Prove the tooling works before you trust it
node knowledge-vault/scripts/validate-vault.mjs --vault knowledge-vault/templates/starter-bundle
| Resource | Purpose |
|---|---|
| Knowledge Vault README | Start here — 30-second quickstart |
| Guide | The method, and why each rule exists |
| Adoption Playbook | Steps, taxonomy choice, CI gating, ticket breakdown |
| Obsidian Guide | Graph, canvases, Bases, and the config treaty |
vault-sync skill |
Drift detection and repair (Claude, Gemini, portable; Cursor as a rule) |
The reading layer
Because an OKF bundle is a directory of plain markdown, Obsidian opens it with no conversion
step, and that is where the vault stops feeling like a docs folder: a graph view of the
concept graph (colour-grouped by directory, with orphans deliberately visible because an orphan is
a defect), canvases for relationships a linear document cannot show, and Bases saved
queries including a drift dashboard listing every concept whose verified_against has fallen
behind. knowledge-vault/templates/obsidian/ ships the app, graph and core-plugin config; the
canvases and Bases views ship inside the vault itself. Bases needs Obsidian 1.9+.
Obsidian is not required: no community plugins are needed, and the vault degrades to plain markdown in any editor. But the graph, canvases and dashboard are a large part of what you get.
The 11-Agent Team
| Agent | Role | When to Use |
|---|---|---|
| BSA | Requirements & specs | Starting any feature |
| System Architect | Architecture review | Significant changes |
| FE Developer | Frontend implementation | UI components |
| BE Developer | Backend implementation | API routes, server logic |
| Data Engineer | Database & migrations | Schema changes |
| QAS | Quality assurance | Test validation |
| Security Engineer | Security validation | RLS, vulnerability checks |
| Tech Writer | Documentation | Guides, technical content |
| DPE | Data provisioning | Test data, seeds |
| RTE | Release coordination | CI/CD, deployments |
| TDM | Coordination | Blockers, escalation |
See AGENTS.md for complete reference with invocation examples.
Domain Adaptation Guide
The harness patterns work beyond software engineering:
Marketing Team Example
| SWE Concept | Marketing Adaptation |
|---|---|
| BSA (specs) | Campaign Brief Writer |
| Code Review | Asset Review |
/pre-pr |
/pre-launch |
| Pattern Library | Brand Guidelines |
Research Team Example
| SWE Concept | Research Adaptation |
|---|---|
| User Stories | Research Questions |
| Test Cases | Validation Criteria |
| CI/CD | Peer Review Pipeline |
| Documentation | Literature Notes |
What Makes This Different
Round Table Philosophy
Human and AI input have equal weight. No hierarchy, just expertise.
Stop-the-Line Authority
Any agent can halt work for architectural or security concerns.
Pattern Discovery Protocol
“Search First, Reuse Always, Create Only When Necessary”
Evidence-Based Delivery
All work requires verifiable evidence. No “trust me, it works.”
vNext Workflow Contract (v1.4)
Note from the Author: It became apparent early on that some of the autonomy and alignment we’d lost in our original harness was not going to work. This re-introduces strong solo and larger orchestration hats with selection criteria. Gates for QAS cover all scenarios.
Complete Agent Flow
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ SAFe AGENTIC WORKFLOW - vNext │
└─────────────────────────────────────────────────────────────────────────────────────────┘
┌──────────────┐
│ USER/POPM │
│ Creates │
│ Linear │
│ Ticket │
└──────┬───────┘
│
▼
┌────────────────────────┐
│ BSA │
│ • Defines AC/DoD │
│ • Pattern discovery │
│ • Creates spec │
└────────────┬───────────┘
│
┌──────────────────┴──────────────────┐
│ STOP-THE-LINE GATE │
│ AC/DoD exists? YES → Proceed │
│ NO → STOP │
└──────────────────┬──────────────────┘
│
┌──────────────────────┼──────────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ BE-DEVELOPER │ │ FE-DEVELOPER │ │ DATA-ENGINEER │
│ Exit: "Ready │ │ Exit: "Ready │ │ Exit: "Ready │
│ for QAS" │ │ for QAS" │ │ for QAS" │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
└──────────────────────┼──────────────────────┘
▼
┌─────────────────────────────────┐
│ QAS (GATE OWNER) │
│ • Iteration authority │
│ • Bounce back repeatedly │
│ • Final evidence to Linear │
│ Exit: "Approved for RTE" │
└────────────┬────────────────────┘
▼
┌─────────────────────────────────┐
│ RTE (PR SHEPHERD) │
│ • PR creation (from spec) │
│ • CI/CD monitoring │
│ • NO code, NO merge │
│ Exit: "Ready for HITL Review" │
└────────────┬────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ 3-STAGE PR REVIEW │
│ Stage 1: System Architect (pattern) │
│ Stage 2: ARCHitect-in-CLI (architecture) │
│ Stage 3: HITL ({{AUTHOR_NAME}}) → MERGE │
└─────────────────────────────────────────────┘
Exit States
┌─────────────────┬───────────────────────────────────────────┐
│ Role │ Exit State │
├─────────────────┼───────────────────────────────────────────┤
│ BE-Developer │ "Ready for QAS" │
│ FE-Developer │ "Ready for QAS" │
│ Data-Engineer │ "Ready for QAS" │
│ QAS │ "Approved for RTE" │
│ RTE │ "Ready for HITL Review" │
│ System Architect│ "Stage 1 Approved - Ready for ARCHitect" │
│ HITL │ MERGED │
└─────────────────┴───────────────────────────────────────────┘
Gate Quick Reference
┌─────────────────┬─────────────────┬─────────────────────────┐
│ Gate │ Owner │ Blocking? │
├─────────────────┼─────────────────┼─────────────────────────┤
│ Stop-the-Line │ Implementer │ YES - no AC = no work │
│ QAS Gate │ QAS │ YES - no approval = stop│
│ Stage 1 Review │ System Architect│ YES - pattern check │
│ Stage 2 Review │ ARCHitect-CLI │ YES - architecture check│
│ HITL Merge │ {{AUTHOR_NAME}} │ YES - final authority │
└─────────────────┴─────────────────┴─────────────────────────┘
Role Collapsing ({{TICKET_PREFIX}}-499)
┌─────────────────────────────────────────────────────────────┐
│ ROLE COLLAPSING AUTHORITY │
├─────────────────────────────────────────────────────────────┤
│ │
│ COLLAPSIBLE: │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ RTE (Release Train Engineer) │ │
│ │ • PR creation can be done by implementer │ │
│ │ • Use when: Simple PRs, single-agent work │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ NOT COLLAPSIBLE (Independence Gates): │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ QAS (Quality Assurance Specialist) │ │
│ │ • ALWAYS spawn subagent - never self-review │ │
│ │ • Rationale: Self-review bias, quality enforcement │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ Security Engineer │ │
│ │ • ALWAYS spawn subagent - never self-audit │ │
│ │ • Rationale: Security blindness, conflict of interest│ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Collapsed Workflow Example
Standard Workflow:
Implementer → QAS → RTE → HITL
│
└─ RTE handles PR creation
Collapsed Workflow (RTE collapsed):
Implementer → QAS → [Implementer handles PR] → HITL
│
└─ QAS gate ALWAYS present, never collapsed
Note: Quality gates are immutable. QAS and SecEng cannot be collapsed.
See Agent Workflow SOP v1.4 for complete details.
Important Caveats
- Multi-provider: Supports Claude Code, Gemini CLI, Codex CLI, and Cursor IDE
- Template-ready: All project-specific values use
{{PLACEHOLDER}}tokens - Provider maturity varies: Claude Code has the deepest integration; other providers are newer
- Domain examples: Non-SWE adaptations (marketing, research) are documented but not yet validated
Repository Structure
.claude/ # Claude Code harness (primary provider)
├── commands/ # 24 slash commands for workflow automation
├── skills/ # 20 model-invoked skills for domain expertise
├── agents/ # 11 SAFe agent profiles
├── team-config.json # Agent Teams settings (optional, experimental)
└── SETUP.md # Installation and customization guide
.gemini/ # Gemini CLI harness (secondary provider)
├── commands/ # 30 TOML commands (namespaced: /workflow:*, /local:*, /remote:*, /media:*)
├── skills/ # 19 model-invoked skills (team-coordination is Claude-only)
├── settings.json # Configuration (model, hooks, policy, security)
├── GEMINI.md # System instructions
└── README.md # Gemini-specific setup guide
.codex/ # Codex CLI harness (reads AGENTS.md, TOML config, MCP native)
├── config.toml # Codex CLI configuration (model, approval policy, sandbox)
└── README.md # Codex-specific setup guide
.cursor/ # Cursor IDE harness (glob-based .mdc rules, background agents)
└── rules/ # .mdc rule files with YAML frontmatter activation
├── 00-02 # Always-apply core rules (SAFe, git, patterns)
├── 03 # SAFe x AI-DLC program cadence (manual activation)
├── 04 # Knowledge-vault conventions (manual activation)
├── 10-13 # Auto-attached tech rules (Python, React, SQL, tests)
├── 20-23 # Agent-role rules (Architect, Backend, QAS, Security)
└── 30-31 # Background agents and MCP integration
.agents/ # Shared agent skills (discovered by Codex and other agents)
└── skills/ # 20 cross-provider skills (api-patterns, safe-workflow, etc.)
knowledge-vault/ # OKF knowledge-base subsystem (optional)
├── docs/ # Method, playbook, build prompts, Obsidian guide
├── templates/ # Starter bundle, Obsidian config, CI workflow
├── scripts/ # validate-vault.mjs (zero dependencies)
└── tests/ # Proof that each validator gate fails when broken
dark-factory/ # tmux Agent Teams infrastructure (optional)
├── scripts/ # factory-setup, start, stop, status, attach
├── templates/ # tmux.conf, team layouts, merge queue ruleset
└── docs/ # Dark Factory guide, Cursor SSH, merge queue policy
docs/ # Additional documentation
├── guides/ # Methodology and adoption guides (incl. SAFe x AI-DLC)
├── whitepapers/ # Harness architecture and philosophy
└── onboarding/ # Getting started guides
specs_templates/ # Spec, planning, PI planning, and program templates
Citation
Download: CITATION.bib | CITATION.cff
APA 7th Edition
{{AUTHOR_LAST_NAME}}, {{AUTHOR_INITIALS}}, & {{PROJECT_SHORT}} Development Team. (2025). Evidence-based multi-agent
development: A SAFe framework implementation with Claude Code [White paper].
https://github.com/{{GITHUB_ORG}}/{{PROJECT_REPO}}
Contributing
We welcome contributions:
- Patterns: Share production-tested patterns
- Case Studies: Document your implementation experience
- Research: Explore open questions from Section 10
- Improvements: Suggest methodology enhancements
See CONTRIBUTING.md for guidelines.
License
MIT License - See LICENSE for details.
Attribution
This project is the Words To Film By™ multi-agent harness, adapted for SAFe development workflows.
Creator: J. Scott Graham (@cheddarfox) - jscottgraham.us Organization: ByBren, LLC Enterprise: Words To Film By™
If you use this harness in your own projects, you must include attribution. See NOTICE for details.
Historical Context: Evolved from Auggie’s Architect Handbook
Words To Film By™ Website • Contact • Sponsor
“Your AI team, ready to work.”
Version: v2.11.1 Status: Production-validated, multi-provider (Claude Code + Gemini CLI + Codex CLI + Cursor IDE)
Recommended Tools
Try a different keyword or remove a filter.
Install
npx skillfish add bybren-llc/safe-agentic-workflow