security-audit-bybren-llc-safe-agentic-workfl
RLS validation, security audits, OWASP compliance, and vulnerability scanning. Use when validating RLS policies, auditing API routes, or sca
Open source Repository Open in the app JSON README (API)
About
RLS validation, security audits, OWASP compliance, and vulnerability scanning. Use when validating RLS policies, auditing API routes, or scanning for security issues.
Details
- Kind
- Agent skills
- Topic
- Security & identity
- Publisher
- bybren-llc
- Origin
- majiayu
- Category
- ferramentas
- Stars
- 409
- Forks
- 89
- Open pull requests
- 1
- Last push
- 2026-07-20T22:11:56Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-09-02 18:12:55
- Updated
- 2026-09-02 18:12:55
- Origin id
bybren-llc/safe-agentic-workflow/.claude/skills/security-audit/SKILL.md@main
README
# SAW — SAFe Agentic Workflow
### AI Agent Harness for Multi-Agent Team Workflows
**A Production-Tested Three-Layer Architecture for Coordinated AI Teams**
<p align="center">
<img src="https://img.shields.io/badge/version-v2.11.1-blue?style=flat-square" alt="Version">
<img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License">
<img src="https://img.shields.io/badge/template-ready-brightgreen?style=flat-square" alt="Template Ready">
<img src="https://img.shields.io/badge/tests-382%2F382-brightgreen?style=flat-square" alt="Tests">
<a href="https://deepwiki.com/bybren-llc/safe-agentic-workflow">
<img src="https://img.shields.io/badge/DeepWiki-bybren--llc%2Fsafe--agentic--workflow-blue?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCI+PHBhdGggZD0iTTQgMTloMTYiLz48cGF0aCBkPSJNNCAxNWg4Ii8+PHBhdGggZD0iTTQgMTFoMTIiLz48cGF0aCBkPSJNNCA3aDE2Ii8+PC9zdmc+" alt="DeepWiki">
</a>
</p>
<p align="center">
<a href=".claude/agents/">
<img src="https://img.shields.io/badge/agents-11%20SAFe%20roles-red?style=flat-square" alt="Agents">
</a>
<a href=".claude/skills/">
<img src="https://img.shields.io/badge/skills-20%20model--invoked-purple?style=flat-square" alt="Skills">
</a>
<a href=".claude/commands/">
<img src="https://img.shields.io/badge/commands-24%20workflows-orange?style=flat-square" alt="Commands">
</a>
<a href=".cursor/rules/">
<img src="https://img.shields.io/badge/cursor%20rules-18-00D084?style=flat-square" alt="Cursor Rules">
</a>
</p>
<p align="center">
<strong>Supported AI Providers</strong><br>
<a href=".claude/">
<img src="https://img.shields.io/badge/Claude_Code-Anthropic-orange?style=flat-square&logo=anthropic" alt="Claude Code">
</a>
<a href=".gemini/">
<img src="https://img.shields.io/badge/Gemini_CLI-Google-blue?style=flat-square&logo=google" alt="Gemini CLI">
</a>
<a href=".codex/">
<img src="https://img.shields.io/badge/Codex_CLI-OpenAI-412991?style=flat-square&logo=openai" alt="Codex CLI">
</a>
<a href=".cursor/rules/">
<img src="https://img.shields.io/badge/Cursor_IDE-Anysphere-00D084?style=flat-square" alt="Cursor IDE">
</a>
</p>
> **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](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](dark-factory/README.md))
- **Knowledge Vault** - Evidence-verified knowledge base with a drift-detecting validator ([guide](knowledge-vault/README.md))
> **Origin**: 5 months production use, 169 issues, 2,193 commits. Implements patterns from
> [6 Anthropic engineering papers](#implementing-anthropics-research) and [SAFe methodology](https://scaledagileframework.com/).
---
## Quick Start (30 seconds)
### Claude Code (Anthropic)
```bash
# 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)
```bash
# 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)
```bash
# 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)
```bash
# 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):
```bash
# 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):
```bash
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](docs/HARNESS_SYNC_GUIDE.md) for the full reference and
> [Upgrade Guide](docs/releases/v2.10.0-UPGRADE.md) for rollback options.
---
## The Three-Layer Architecture
```text
┌──────────────────────────────────────────────────────────────────────┐
│ 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
<details>
<summary><strong>For Practitioners</strong> - I want to use this today</summary>
### Getting Started
1. Run `bash scripts/setup-template.sh` to customize placeholders
2. Read the [Getting Started Guide](docs/guides/GETTING-STARTED.md) for the full walkthrough
3. Run `/start-work` on your first ticket
**Adopting into an existing repo?** See the [Workspace Adoption Guide](docs/guides/WORKSPACE-ADOPTION-GUIDE.md).
**Upgrading from a previous version?** See [Keeping the Harness Updated](docs/guides/WORKSPACE-ADOPTION-GUIDE.md#keeping-the-harness-updated).
**Syncing your fork with upstream?** See the [Harness Sync Guide](docs/HARNESS_SYNC_GUIDE.md).
**Planning a multi-issue program?** See the [SAFe x AI-DLC Methodology](docs/guides/SAFE-AI-DLC-METHODOLOGY.md).
**Building a knowledge base?** See the [Knowledge Vault](knowledge-vault/README.md).
### 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](.claude/SETUP.md)
</details>
<details>
<summary><strong>For Researchers</strong> - I want to understand the methodology</summary>
### Research Foundation
This harness implements patterns from 6 Anthropic engineering papers (see [below](#implementing-anthropics-research)).
See `docs/whitepapers/` for methodology deep-dives and comparative analysis.
</details>
<details>
<summary><strong>For Leaders</strong> - I want to understand adoption</summary>
### 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
</details>
---
## Gemini CLI Integration
<details>
<summary><strong>Why Gemini CLI?</strong> - Unique capabilities and when to use it</summary>
### 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
- Production-tested workflow (5+ months validated)
### Gemini CLI Quick Reference
```bash
# Installation
npm install -g @google/gemini-cli
# Authentication (choose one)
export GEMINI_API_KEY="your-api-key"
# or
gcloud auth application-default login
# Start Gemini CLI
gemini
# List available commands
/help
# List available skills
/skills
```
### Command Syntax Differences
| Action | Claude Code | Gemini CLI |
|--------|-------------|------------|
| Start work | `/start-work {{TICKET_PREFIX}}-123` | `/workflow:start-work {{TICKET_PREFIX}}-123` |
| Pre-PR check | `/pre-pr` | `/workflow:pre-pr` |
| Local sync | `/local-sync` | `/local:sync` |
| Remote deploy | `/remote-deploy` | `/remote:deploy` |
| Search patterns | `/search-pattern "pattern"` | `/search-pattern "pattern"` |
### Gemini CLI Documentation
- **Official Docs**: [geminicli.com](https://geminicli.com)
- **Installation**: [geminicli.com/docs/get-started/installation/](https://geminicli.com/docs/get-started/installation/)
- **Authentication**: [geminicli.com/docs/get-started/authentication/](https://geminicli.com/docs/get-started/authentication/)
- **Custom Commands**: [geminicli.com/docs/cli/custom-commands/](https://geminicli.com/docs/cli/custom-commands/)
- **Skills**: [geminicli.com/docs/cli/skills/](https://geminicli.com/docs/cli/skills/)
</details>
---
## Implementing Anthropic's Research
This harness directly implements patterns from Anthropic's engineering papers:
| Paper | What We Implement |
| ----------------------------------------------------------------------------------------------------------- | -------------------------- |
| [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) | 11-agent team structure |
| [Effective Harnesses](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) | Three-layer architecture |
| [Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) | 20 model-invoked skills |
| [Skills Announcement](https://www.anthropic.com/news/skills) | Skills 2.0 frontmatter, trigger patterns |
| [Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) | Tool restrictions per role |
> "The best harness is one you forget exists." — [Agent Perspective](docs/whitepapers/CLAUDE-CODE-HARNESS-AGENT-PERSPECTIVE.md)
---
## SAFe Foundation
<details>
<summary><strong>For Agile Practitioners</strong> - Deep dive into SAFe integration</summary>
This harness maps SAFe roles to AI agents:
| SAFe Role | Agent | Responsibility |
| ------------------------ | ---------------- | --------------------------------- |
| Business Systems Analyst | BSA | Requirements, acceptance criteria |
| System Architect | System Architect | Architecture decisions, ADRs |
| Product Owner | POPM (human) | Final approval on deliverables |
| Scrum Master | TDM | Coordination, blocker escalation |
| Release Train Engineer | RTE | CI/CD, release coordination |
### SAFe Concepts Implemented
- **Epic → Feature → Story → Enabler** hierarchy in specs
- **Sprint cycles** with velocity tracking (or **Bolts** — see below)
- **Evidence-based delivery** with Linear integration
- **Specs-driven workflow** - BSA plans, developers execute
</details>
---
## 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](https://aws.amazon.com/blogs/devops/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](docs/guides/SAFE-AI-DLC-METHODOLOGY.md) | 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](specs_templates/program_template.md) | 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](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
(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](knowledge-vault/docs/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](knowledge-vault/docs/SAW-VAULT-BUILD.md) | **This repo's maintainers** — pre-scoped to {{PROJECT_SHORT}} and runnable as-is, with a ready-to-file ticket breakdown. |
```bash
# 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](knowledge-vault/README.md) | Start here — 30-second quickstart |
| [Guide](knowledge-vault/docs/GUIDE.md) | The method, and why each rule exists |
| [Adoption Playbook](knowledge-vault/docs/ADOPTION-PLAYBOOK.md) | Steps, taxonomy choice, CI gating, ticket breakdown |
| [Obsidian Guide](knowledge-vault/docs/OBSIDIAN-GUIDE.md) | 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](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.
```
<details>
<summary><strong>Part 1: Core Workflow Architecture</strong> - Complete flow diagrams</summary>
### 1.1 Complete Agent Flow (Detailed)
```
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ 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, route to BSA │ │
│ └────────────────────────────────┘ │
└──────────────────┬──────────────────┘
│
┌──────────────────────┼──────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ BE-DEVELOPER │ │ FE-DEVELOPER │ │ DATA-ENGINEER │
│ │ │ │ │ │
│ Owns: │ │ Owns: │ │ Owns: │
│ • API routes │ │ • UI components│ │ • Schema/DB │
│ • Server logic │ │ • Client logic │ │ • Migrations │
│ • SAFe commits │ │ • SAFe commits │ │ • SAFe commits │
│ │ │ │ │ │
│ Must NOT: │ │ Must NOT: │ │ Must NOT: │
│ • Create PRs │ │ • Create PRs │ │ • Create PRs │
│ • Merge │ │ • Merge │ │ • Merge │
│ │ │ │ │ • Skip ARCHitect│
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
│ Exit: "Ready for QAS" │
└──────────────────────┼──────────────────────┘
│
▼
┌─────────────────────────────────┐
│ QAS │
│ (GATE OWNER) │
│ │
│ Powers: │
│ • Iteration authority │
│ • Bounce back repeatedly │
│ • Route to specialists │
│ • Final evidence to Linear │
│ │
│ Tools (Linear MCP): │
│ • mcp__{{MCP_LINEAR_SERVER}}__ │
│ create_comment │
│ • mcp__{{MCP_LINEAR_SERVER}}__ │
│ update_issue │
│ • mcp__{{MCP_LINEAR_SERVER}}__ │
│ list_comments │
└────────────┬────────────────────┘
│
┌────────────────┴────────────────┐
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ BLOCKED │ │ APPROVED │
│ │ │ │
│ Routes to: │ │ Exit State: │
│ • Implementer │ │ "Approved │
│ • Tech Writer │ │ for RTE" │
│ • Sys Architect│ │ │
└────────┬────────┘ └────────┬────────┘
│ │
│ (Loop until fixed) │
└──────────────────────────────────┤
│
▼
┌─────────────────────────────────┐
│ RTE │
│ (PR SHEPHERD) │
│ │
│ Owns: │
│ • PR creation (from spec) │
│ • CI/CD monitoring │
│ • Evidence assembly │
│ • PR metadata edits │
│ │
│ Must NOT: │
│ • Write product code │
│ • Merge PRs │
│ • Approve own work │
└────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ 3-STAGE PR REVIEW │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ STAGE 1: System Architect │ │
│ │ • Pattern compliance │ │
│ │ • RLS enforcement │ │
│ │ • Technical validation │ │
│ │ → Exit: "Stage 1 Approved" │ │
│ └─────────────────┬───────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ STAGE 2: ARCHitect-in-CLI │ │
│ │ • Comprehensive review │ │
│ │ • Architecture validation │ │
│ │ • Security verification │ │
│ │ → Exit: "Stage 2 Approved" │ │
│ └─────────────────┬───────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ STAGE 3: HITL ({{AUTHOR_NAME}}) │ │
│ │ • Final human review │ │
│ │ • Merge authority │ │
│ │ → Action: MERGE │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
```
### 1.2 Exit States Flow (with Handoff Statements)
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ EXIT STATE PROGRESSION │
└─────────────────────────────────────────────────────────────────────────────┘
IMPLEMENTATION QAS RTE HITL
───────────── ───── ───── ──────
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Coding │ │ Validating │ │ Shepherding│ │ Reviewing │
│ Testing │ │ Iterating │ │ CI/CD │ │ Merging │
│ Commits │ │ Evidence │ │ Assembling │ │ │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │ │
▼ ▼ ▼ ▼
╔═════════════╗ ╔═════════════╗ ╔═════════════╗ ╔═════════════╗
║ "Ready ║ ────▶ ║ "Approved ║ ────▶ ║ "Ready for ║ ──▶ ║ MERGED ║
║ for QAS" ║ ║ for RTE" ║ ║ HITL Review"║ ║ ║
╚═════════════╝ ╚═════════════╝ ╚═════════════╝ ╚═════════════╝
│ │ │
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Handoff │ │ Handoff │ │ Handoff │
│ Statement: │ │ Statement: │ │ Statement: │
│ │ │ │ │ │
│ "BE/FE/DE │ │ "QAS valid- │ │ "PR #XXX │
│ impl done │ │ ation done │ │ ready for │
│ for {{TICKET_PREFIX}}-X. │ │ for {{TICKET_PREFIX}}-X. │ │ HITL review.│
│ All valid- │ │ All PASSED. │ │ CI green, │
│ ation pass. │ │ Approved │ │ reviews │
│ AC/DoD │ │ for RTE." │ │ complete." │
│ confirmed. │ │ │ │ │
│ Ready for │ │ │ │ │
│ QAS." │ │ │ │ │
└─────────────┘ └─────────────┘ └─────────────┘
```
### 1.3 Stop-the-Line Gate (Mandatory)
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ STOP-THE-LINE GATE (MANDATORY) │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ TICKET ARRIVES │
│ (Linear {{TICKET_PREFIX}}-X) │
└────────┬────────┘
│
▼
┌─────────────────────────┐
│ CHECK: AC/DoD EXISTS? │
└────────────┬────────────┘
│
┌─────────────────┴─────────────────┐
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ YES │ │ NO │
│ │ │ │
│ AC/DoD is │ │ AC/DoD missing │
│ defined and │ │ or unclear │
│ clear │ │ │
└────────┬────────┘ └────────┬────────┘
│ │
▼ ▼
┌─────────────────┐ ╔═════════════════╗
│ PROCEED │ ║ FULL STOP ║
│ │ ║ ║
│ Begin │ ║ • Do NOT ║
│ implementation │ ║ proceed ║
│ │ ║ ║
│ │ ║ • Route back ║
│ │ ║ to BSA/POPM ║
│ │ ║ ║
│ │ ║ • You are NOT ║
│ │ ║ responsible ║
│ │ ║ for inventing║
│ │ ║ AC/DoD ║
└─────────────────┘ ╚═════════════════╝
┌───────────────────────────────────────────────────────────────────────────┐
│ POLICY: Implementation agents (BE/FE/DE) must verify AC/DoD exists │
│ before starting ANY work. This is a hard gate, not optional. │
└───────────────────────────────────────────────────────────────────────────┘
```
### 1.4 QAS Iteration Loop
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ QAS ITERATION AUTHORITY │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐
│ WORK ARRIVES │
│ "Ready for QAS"│
└────────┬────────┘
│
▼
┌─────────────────────────┐
│ QAS VALIDATES WORK │
│ │
│ • Run test suites │
│ • Check AC/DoD │
│ • Verify evidence │
│ • Review documentation │
└────────────┬────────────┘
│
┌─────────────────┴─────────────────┐
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ ALL PASS ✓ │ │ ISSUES FOUND │
│ │ │ │
│ • Tests pass │ │ • Tests fail │
│ • AC/DoD met │ │ • AC incomplete│
│ • Evidence OK │ │ • Docs missing │
│ • Docs match │ │ • Pattern issue│
└────────┬────────┘ └────────┬────────┘
│ │
▼ ▼
╔═════════════════╗ ┌─────────────────┐
║ APPROVED ║ │ BLOCKED │
║ ║ │ │
║ Post evidence ║ │ Route to: │
║ to Linear ║ │ │
║ ║ │ ┌───────────┐ │
║ Exit: "Approved║ │ │Code bugs │──┼──▶ @be-developer
║ for RTE" ║ │ └───────────┘ │ @fe-developer
╚═════════════════╝ │ ┌───────────┐ │
│ │Validation │──┼──▶ Implementer
│ │fails │ │
│ └───────────┘ │
│ ┌───────────┐ │
│ │Doc gaps │──┼──▶ @tech-writer
│ └───────────┘ │
│ ┌───────────┐ │
│ │Pattern │──┼──▶ @system-architect
│ │violation │ │
│ └───────────┘ │
│ ┌───────────┐ │
│ │AC/DoD │──┼──▶ @bsa
│ │missing │ │
│ └───────────┘ │
└────────┬────────┘
│
│ (Fix and return)
│
▼
┌─────────────────┐
│ REPEAT UNTIL │
│ ALL PASS │
│ │
│ QAS has full │
│ iteration │
│ authority │
└─────────────────┘
```
</details>
<details>
<summary><strong>Part 2: Role Definitions</strong> - Contract specifications for each role</summary>
### 2.1 Role Ownership Matrix
```
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ ROLE OWNERSHIP MATRIX │
├─────────────────┬───────────────────────────────────────────────────────────────────────┤
│ │ RESPONSIBILITIES │
│ ROLE ├───────────┬───────────┬───────────┬───────────┬───────────┬──────────┤
│ │ CODE │ COMMITS │ PR │ MERGE │ EVIDENCE │ GATE │
├─────────────────┼───────────┼───────────┼───────────┼───────────┼───────────┼──────────┤
│ BE-Developer │ ✓ │ ✓ │ ✗ │ ✗ │ Partial │ ✗ │
│ FE-Developer │ ✓ │ ✓ │ ✗ │ ✗ │ Partial │ ✗ │
│ Data-Engineer │ ✓ │ ✓ │ ✗ │ ✗ │ Partial │ ✗ │
├─────────────────┼───────────┼───────────┼───────────┼───────────┼───────────┼──────────┤
│ QAS │ ✗ │ ✗ │ ✗ │ ✗ │ ✓ │ ✓ │
├─────────────────┼───────────┼───────────┼───────────┼───────────┼───────────┼──────────┤
│ RTE │ ✗ │ Metadata │ ✓ │ ✗ │ Assembly │ ✗ │
├─────────────────┼───────────┼───────────┼───────────┼───────────┼───────────┼──────────┤
│ System Architect│ Review │ ✗ │ Stage 1 │ ✗ │ Review │ Stage 1 │
│ ARCHitect-CLI │ Review │ ✗ │ Stage 2 │ ✗ │ Review │ Stage 2 │
├─────────────────┼───────────┼───────────┼───────────┼───────────┼───────────┼──────────┤
│ HITL ({{AUTHOR_NAME}}) │ Review │ ✗ │ Stage 3 │ ✓ │ Final │ Stage 3 │
└─────────────────┴───────────┴───────────┴───────────┴───────────┴───────────┴──────────┘
Legend:
✓ = Owns/Authorized
✗ = Not Authorized
Partial = Captures during work, QAS collects
Review = Read-only review authority
Metadata = PR title, labels, body only (not code)
Assembly = Collects from all agents
```
### 2.2 Implementation Agents Contract (BE/FE/DE)
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ IMPLEMENTATION AGENT CONTRACT │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ PRECONDITION (Mandatory Gate): │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Verify AC/DoD exists → If missing, STOP and route to BSA/POPM │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ OWNS: MUST NOT: │
│ ├─ Code changes ├─ Create PRs │
│ ├─ Atomic SAFe commits ├─ Merge to dev/master │
│ └─ Local validation └─ Invent AC/DoD │
│ │
│ MUST DO: │
│ ├─ Run validation loop until ALL pass │
│ ├─ Confirm ALL AC/DoD satisfied │
│ ├─ Commit own work (SAFe format) │
│ └─ Provide handoff statement │
│ │
│ EXIT STATE: "Ready for QAS" │
│ │
│ HANDOFF TEMPLATE: │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ "[BE/FE/DE] implementation complete for {{TICKET_PREFIX}}-XXX. │ │
│ │ All validation passing. AC/DoD confirmed. │ │
│ │ Ready for QAS review." │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### 2.3 QAS Gate Owner Contract
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ QAS GATE OWNER CONTRACT │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ROLE: GATE (not just validator) │
│ ─────────────────────────────── │
│ Work does NOT proceed without QAS approval. │
│ │
│ OWNS: MUST NOT: │
│ ├─ Independent verification ├─ Modify product code │
│ ├─ Iteration authority ├─ Skip AC/DoD verification │
│ ├─ QA artifacts └─ Approve incomplete work │
│ └─ Final evidence to Linear │
│ │
│ LINEAR MCP TOOLS: │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • mcp__{{MCP_LINEAR_SERVER}}__create_comment (post evidence) │ │
│ │ • mcp__{{MCP_LINEAR_SERVER}}__update_issue (update status) │ │
│ │ • mcp__{{MCP_LINEAR_SERVER}}__list_comments (read context) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ROUTING AUTHORITY: │
│ ┌────────────────┬──────────────────┬───────────────────────────────┐ │
│ │ Issue Type │ Route To │ Action │ │
│ ├────────────────┼──────────────────┼───────────────────────────────┤ │
│ │ Code bugs │ @be/fe-developer │ Return with specific issues │ │
│ │ Validation fail│ Implementer │ Return with failure output │ │
│ │ Doc mismatch │ @tech-writer │ Route for documentation fix │ │
│ │ Pattern issue │ @system-architect│ Escalate for pattern review │ │
│ │ AC/DoD missing │ @bsa │ Cannot approve without AC │ │
│ └────────────────┴──────────────────┴───────────────────────────────┘ │
│ │
│ EXIT STATE: "Approved for RTE" │
│ │
│ HANDOFF TEMPLATE: │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ "QAS validation complete for {{TICKET_PREFIX}}-XXX. │ │
│ │ All criteria PASSED. Evidence posted to Linear. │ │
│ │ Approved for RTE." │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### 2.4 RTE PR Shepherd Contract
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ RTE PR SHEPHERD CONTRACT │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ PREREQUISITE (QAS Gate): │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Work MUST have QAS approval ("Approved for RTE" status) │ │
│ │ Evidence MUST be posted to Linear │ │
│ │ If QAS not approved → STOP and wait │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ OWNS: MUST NOT (NEVER): │
│ ├─ PR creation (from spec) ├─ Merge PRs (HITL only) │
│ ├─ CI/CD monitoring ├─ Write product code │
│ ├─ Evidence assembly ├─ Approve own work │
│ ├─ PR metadata (title, labels, body) └─ Have merge cmd examples │
│ └─ Coordination between agents │
│ │
│ IF CI FAILS: │
│ ┌────────────────────────────┬─────────────────────────────────────┐ │
│ │ Failure Type │ Route To │ │
│ ├────────────────────────────┼─────────────────────────────────────┤ │
│ │ Structural/pattern issues │ System Architect │ │
│ │ Implementation bugs │ Original implementer (BE/FE/DE) │ │
│ │ NEVER fix code yourself │ --- │ │
│ └────────────────────────────┴─────────────────────────────────────┘ │
│ │
│ EXIT STATE: "Ready for HITL Review" │
│ │
│ HANDOFF TEMPLATE: │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ "PR #XXX for {{TICKET_PREFIX}}-YYY is Ready for HITL Review. │ │
│ │ All CI green, reviews complete, evidence attached. │ │
│ │ Awaiting final merge approval from {{AUTHOR_NAME}}." │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### 2.5 System Architect Stage 1 Contract
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ SYSTEM ARCHITECT STAGE 1 CONTRACT │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ROLE: Stage 1 of 3-Stage PR Review Process │
│ ─────────────────────────────────────────── │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Stage 1: System Architect (you) - Technical/pattern validation │ │
│ │ Stage 2: ARCHitect-in-CLI - Comprehensive review │ │
│ │ Stage 3: HITL ({{AUTHOR_NAME}}) - Final merge authority │ │
│ └───────────