SAW Knowledge Vault
Root index for the SAFe Agentic Workflow knowledge bundle: both doors into 221 evidence-verified concepts.
Open source Repository Open in the app JSON README (API)
About
# SAW Knowledge Vault
This vault is a **map of the SAFe Agentic Workflow harness, not the harness itself**. Every concept
here is a short card that summarizes and links its sources; the code stays authoritative. Each card
records `verified_against` — the git SHA its claims were last checked at. That is what makes
staleness *computed* rather than felt: when a card's SHA falls behind the current baseline, the card
is provably unverified, whether or not anything in it happens to still be true. A citation is not
re-verification. Only re-deriving a card from source moves its SHA forward.
**Baseline: `fd0fc6a`.** Cards verified against that SHA are current; anything behind it is in the
drift queue below.
## Two doors
Pick by what you are doing, not by what you want to know:
- [Start Here](start-here.md) — the **learning door**. An ordered path where every step explains why
it comes where it does. Take this if the harness is new to you.
- This page — the **reference door**. A cascade of
Details
- Kind
- OKF bundles
- Topic
- Security & identity
- Publisher
- bybren-llc
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Stars
- 406
- Forks
- 88
- Open pull requests
- 1
- Last push
- 2026-07-20T22:11:56Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-09-09 12:02:17
- Updated
- 2026-09-09 12:02:17
- Origin id
bybren-llc/safe-agentic-workflow:docs/knowledge-vault/index.md
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 │ │
│ └───────────