SAFe Agent Team Quick Reference

Philosophy: "Search First, Reuse Always, Create Only When Necessary"

Pattern discovery is MANDATORY before implementation.

Team Culture: "We work as a round table team that has 4 pillars of SAFe inscribed on that round table. It means something."

Documentation

Workflow SOPs:

Agent Workflow SOP v1.4 - vNext contract, Exit States, Role Collapsing (REN-497/499)
Agent Configuration SOP - Tool restrictions, model selection
ARCHitect-in-CLI Role - Primary orchestrator definition

CI/CD Documentation:

CI/CD Pipeline Guide - Pipeline implementation guide

Database SOPs:

RLS Migration SOP - MANDATORY for Data Engineer

Project Standards:

Harness Whitepaper - Complete harness architecture
Agent Perspective - Why the harness works
SAFe Methodology - This repository

When to Use Which Agent

Agent Role	Use Case	Success Criteria	Primary Tools
TDM (Technical Delivery Manager)	Reactive blocker resolution, Linear updates, evidence tracking (NOT orchestration - see v1.3 SOP)	Blockers resolved, evidence attached, Linear updated	Linear, Confluence
BSA (Business Systems Analyst)	Requirements decomposition, acceptance criteria, testing strategy	Clear user stories, testable ACs, QA plan defined	Linear, Confluence, Markdown
System Architect	Pattern validation, Stage 1 PR review, migration approval, architectural decisions	ADR created, PR technical review complete, no conflicts	Read, Grep, ADR templates
FE Developer	UI components, client-side logic, user interactions	Lint and build passes	Read, Write, Edit, Bash
BE Developer	API routes, server logic, RLS enforcement	Integration tests pass	Read, Write, Edit, Bash
DE (Data Engineer)	Schema changes, migrations, database architecture	Migration applied, RLS maintained	SQLAlchemy, Alembic, SQL
TW (Technical Writer)	Documentation, guides, technical content	Markdown lint passes	Read, Write, Edit, Grep, Glob, Bash
DPE (Data Provisioning Engineer)	Test data, database access, data validation	Test data available, DB accessible	SQL, pgAdmin, scripts
QAS (Quality Assurance)	GATE OWNER: Execute testing, validate ACs, iteration authority, evidence to Linear	All ACs verified, evidence posted, Exit: "Approved for RTE"	pytest, Playwright, Linear MCP
SecEng (Security Engineer)	Security validation, RLS checks, vulnerability assessment (Independence Gate - not collapsible)	Security audit passed, RLS enforced	RLS scripts, security tools
RTE (Release Train Engineer)	PR SHEPHERD: PR creation, CI/CD monitoring (NO code, NO merge) - Exit: "Ready for HITL"	PR created, CI green, Exit: "Ready for HITL Review"	Git, GitHub CLI, CI tools

Auto-Loaded Skills

Skills are loaded progressively—metadata at startup, full content when context triggers.

Skill	Trigger	Purpose
`safe-workflow`	Commits, branches, PRs	SAFe format, rebase-first workflow
`pattern-discovery`	Before writing code	Pattern-first development (MANDATORY)
`rls-patterns`	Database operations	RLS context helpers (withUserContext, etc.)
`frontend-patterns`	UI work	React 18, Electron, ShadCN patterns
`api-patterns`	API route creation	Route structure, error handling
`testing-patterns`	Writing tests	pytest, Playwright patterns
`orchestration-patterns`	Multi-step work	Agent loop, evidence-based delivery
`agent-coordination`	Multi-agent work	Assignment matrix, escalation patterns
`team-coordination`	Agent Teams spawn	Multi-agent orchestration (experimental)

Note: /skills command has display bug (v2.0.73, GitHub #14733). Skills work but won't show in list. Ask Claude directly: "What skills are available?"

Success Validation Commands

Frontend Development

cd sdk && ruff check . && echo "FE SUCCESS" || echo "FE FAILED"

Backend Development

pytest tests/integration && echo "BE SUCCESS" || echo "BE FAILED"

Pre-Push Validation

make ci && echo "CI SUCCESS" || echo "CI FAILED"

Database Migration

alembic revision --autogenerate -m "migration_name" && alembic upgrade head && echo "MIGRATION SUCCESS" || echo "MIGRATION FAILED"

SAFe Specs-Driven Workflow

Planning Phase (BSA)

# Large initiative → Use planning template
cp specs_templates/planning_template.md specs/{feature}-planning.md
# Fill with Epic → Features → Stories → Enablers

# User story → Use spec template
cp specs_templates/spec_template.md specs/REN-XXX-{feature}-spec.md
# Fill with implementation details

Execution Phase (All Agents)

# 1. Read spec for clear goal
cat specs/REN-XXX-{feature}-spec.md

# 2. Extract:
# - User story (goal)
# - Acceptance criteria (success)
# - Low-level tasks (steps)
# - Demo script (validation)

# 3. Implement using Simon's loop:
# - Clear goal from spec
# - Pattern discovery (codebase + specs)
# - Iterate until demo script passes
# - Escalate if blocked

Pattern Discovery Protocol (MANDATORY)

0. Search Specs Directory (FIRST)

# Find similar implementations in specs
ls specs/*-spec.md | grep "similar_feature"

# Review SAFe user stories
grep -r "As a.*I want to" specs/

# Check patterns from past specs
cat specs/XXX-similar-spec.md

1. Search Codebase

# Search for similar functionality
grep -r "feature_name|functionality" app/

# Find existing helpers
ls lib/ && grep -r "helper_pattern" lib/

# Check components
grep -r "component_pattern" components/

2. Search Session History

# Search agent session todos
grep -r "similar_feature|pattern" ~/.claude/todos/ 2>/dev/null

# Find recent implementation patterns
ls -lt ~/.claude/todos/ | head -20

3. Consult Documentation

CONTRIBUTING.md - Workflow and git process
docs/database/DATA_DICTIONARY.md - Database schema (SINGLE SOURCE OF TRUTH)
docs/database/RLS_IMPLEMENTATION_GUIDE.md - Row Level Security (MANDATORY for DB ops)
docs/security/SECURITY_FIRST_ARCHITECTURE.md - Security patterns

4. Architectural Validation

Propose pattern to System Architect
Get approval before implementation
Document decision in session notes

Agent Workflow

Standard Agent Loop (Per Simon Willison)

Clear Goal - BSA defines with acceptance criteria
Pattern Discovery - Search codebase and sessions
Iterative Problem Solving:
- Implement approach
- Run validation command
- If fails → analyze error, adjust, repeat
- If blocked → escalate to TDM with context
Evidence Attachment - Session ID + validation results in Linear

No Over-Engineering

❌ No file locks
❌ No circuit breakers
❌ No arbitrary retry limits
✅ Let agents iterate until success or blocked
✅ Agent decides when to escalate

Session Archaeology

Monitor Concurrent Sessions

# See active sessions
ls -lt ~/.claude/todos/*.json | head -10

# Check for concurrent work on same files
grep -l "file_path" ~/.claude/todos/*.json

Cross-Agent Coordination

# Find related work by another agent
grep -r "linear_ticket_number" ~/.claude/todos/

# Discover implementation patterns
grep -r "withUserContext|withAdminContext" ~/.claude/todos/

Exit States (vNext Contract)

Each agent has explicit exit states that define handoff points:

┌─────────────────┬───────────────────────────────────────────┐
│ 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      │ J. Scott Graham            │ YES - final authority   │
└─────────────────┴─────────────────┴─────────────────────────┘

Role Collapsing (REN-499)

RTE: Collapsible (PR creation, CI shepherding can be done by implementer)
QAS: NOT collapsible (independence gate - spawn subagent for verification)
SecEng: NOT collapsible (security audit requires independence)

See Agent Workflow SOP v1.4 for details.

Agent Teams (Experimental)

Agent Teams enable real-time multi-agent orchestration using Claude Code's experimental Agent Teams feature. When enabled, agents are spawned as teammates with shared task lists and SAFe quality gates enforced via task dependencies.

Enable: Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in .claude/settings.json
Skill: /team-coordination — patterns for TeamCreate, SendMessage, shared TaskList
Guide: See Agent Teams Guide and Optional Features

Quick Reference

Key Documentation

CONTRIBUTING.md - Complete workflow guide (MANDATORY READ)
docs/database/DATA_DICTIONARY.md - Database schema (SINGLE SOURCE OF TRUTH)
docs/database/RLS_DATABASE_MIGRATION_SOP.md - Schema changes (ARCHitect approval required)
docs/security/SECURITY_FIRST_ARCHITECTURE.md - Security patterns

Agent Files

.claude/agents/bsa.md - Business Systems Analyst
.claude/agents/system-architect.md - System Architect
.claude/agents/tdm.md - Technical Delivery Manager
.claude/agents/fe-developer.md - Frontend Developer
.claude/agents/be-developer.md - Backend Developer
.claude/agents/data-engineer.md - Data Engineer
.claude/agents/data-provisioning-eng.md - Data Provisioning Engineer
.claude/agents/tech-writer.md - Technical Writer
.claude/agents/qas.md - Quality Assurance Specialist
.claude/agents/security-engineer.md - Security Engineer
.claude/agents/rte.md - Release Train Engineer

Human-in-the-Loop (HITL) Model

Product Owner / Product Manager: J. Scott Graham

All work requires evidence in Linear before POPM review
Swimlane workflow: Backlog → Ready → In Progress → Testing → Ready for Review → Done
POPM has final approval on all deliverables

🎯 Agent Invocation Examples

Simple Invocation (Direct Mention)

Use @agent-name for simple, single-step tasks:

# Planning
@bsa Create a spec for user profile API endpoint
@system-architect Review the RLS policy for user_profiles table

# Implementation
@be-developer Implement the GET /api/user/profile endpoint
@fe-developer Create a UserProfile component with form validation
@data-engineer Add email_verified column to users table

# Quality & Documentation
@qas Write integration tests for user profile feature
@security-engineer Audit RLS policies for user_profiles table
@tech-writer Document the user profile API in README

# Coordination
@tdm Coordinate implementation of REN-123 user profile feature
@rte Create PR for REN-123 and run CI validation

Task Tool Invocation (Complex Tasks)

Use Task() for complex, multi-step tasks with detailed instructions:

// BSA: Create comprehensive spec
Task({
  subagent_type: "bsa",
  description: "Create spec for REN-123",
  prompt: `Create comprehensive spec for REN-123 user profile feature.

Requirements:
- User can view and edit their profile
- Profile includes: name, email, bio, avatar
- Email verification required
- Admin can view all profiles

Please:
1. Search for existing user/profile patterns in patterns_library/
2. Create user story with acceptance criteria
3. Define testing strategy (unit, integration, E2E)
4. Add #EXPORT_CRITICAL tags for security requirements
5. Reference relevant patterns from pattern library`,
});

// Backend Developer: Implement with pattern discovery
Task({
  subagent_type: "be-developer",
  description: "Implement REN-123 API",
  prompt: `Read spec at specs/REN-123-user-profile-spec.md

Implement the user profile API endpoints:
1. GET /api/user/profile - Get current user's profile
2. PUT /api/user/profile - Update current user's profile
3. GET /api/admin/users/:id/profile - Admin view any profile

Requirements:
- Use withUserContext for user endpoints
- Use withAdminContext for admin endpoints
- Follow RLS patterns from patterns_library/database/
- Validate input with Pydantic schemas
- Write unit tests for each endpoint

Pattern discovery is MANDATORY before implementation.`,
});

// QAS: Execute comprehensive testing
Task({
  subagent_type: "qas",
  description: "Test REN-123 feature",
  prompt: `Read spec at specs/REN-123-user-profile-spec.md

Execute the testing strategy defined by BSA:

1. Unit Tests:
   - Test Pydantic validation schemas
   - Test RLS context helpers
   - Test error handling

2. Integration Tests:
   - Test GET /api/user/profile with user context
   - Test PUT /api/user/profile with valid/invalid data
   - Test admin endpoints with admin context
   - Test RLS isolation (user A cannot see user B's data)

3. E2E Tests:
   - User can view their profile
   - User can edit their profile
   - Admin can view any profile
   - Unauthorized access is blocked

Validate all acceptance criteria from the spec.`,
});

// TDM: Reactive blocker resolution (NOT orchestration)
Task({
  subagent_type: "tdm",
  description: "Resolve blocker for REN-123",
  prompt: `A blocker has been reported for REN-123.

TDM Responsibilities (per v1.3 SOP):
1. Monitor progress - read session archaeology, Linear, PR comments
2. Identify blocker details - search for "FAILED|error|blocked"
3. Escalate to appropriate specialist to resolve
4. Track evidence - attach session IDs, test results to Linear
5. Update Linear ticket with resolution

NOTE: TDM is REACTIVE, not an orchestrator.
ARCHitect-in-CLI is the primary orchestrator.`,
});

When to Use Which Invocation Method

Scenario	Method	Example
Simple question	Direct mention	`@bsa What patterns exist for user authentication?`
Single-step task	Direct mention	`@be-developer Add logging to the login endpoint`
Multi-step task	Task tool	BSA creating spec with pattern discovery
Complex coordination	Task tool	Multiple agents working on related features
Detailed requirements	Task tool	QAS executing comprehensive test strategy
Blocker resolution	Task tool	TDM investigating and escalating blockers

Pro Tips

Always reference specs: Read spec at specs/REN-XXX-spec.md
Mandate pattern discovery: Pattern discovery is MANDATORY before implementation
Check #EXPORT_CRITICAL tags: Review #EXPORT_CRITICAL tags in spec first
Validate with commands: Use success validation commands from agent prompts
Update Linear: TDM can update Linear with mcp__claude_ai_Linear__create_comment
TDM is reactive: Don't use TDM for orchestration—use ARCHitect-in-CLI

Quick Start: Read CONTRIBUTING.md, search codebase, propose to System Architect, validate with test command, attach evidence to Linear.

Uh oh!