{ "markdown": "# SAW — SAFe Agentic Workflow\n\n### AI Agent Harness for Multi-Agent Team Workflows\n\n**A Production-Tested Three-Layer Architecture for Coordinated AI Teams**\n\n

\n \"Version\"\n \"License\"\n \"Template\n \"Tests\"\n \n \"DeepWiki\"\n \n

\n

\n \n \"Agents\"\n \n \n \"Skills\"\n \n \n \"Commands\"\n \n \n \"Cursor\n \n

\n\n

\n Supported AI Providers
\n \n \"Claude\n \n \n \"Gemini\n \n \n \"Codex\n \n \n \"Cursor\n \n

\n\n> **Template Repository** - Click \"Use this template\" above to create your own AI agent harness.\n> After cloning, run `bash scripts/setup-template.sh` to customize for your project.\n> See [TEMPLATE_SETUP.md](TEMPLATE_SETUP.md) for details.\n\n---\n\n## What This Is\n\nA **production-tested AI agent harness** for teams that want structured AI workflows.\n\n**Multi-provider support**: Works with **Claude Code** (Anthropic), **Gemini CLI** (Google), **Codex CLI** (OpenAI), and **Cursor IDE** (Anysphere).\n\n**Built on SAFe methodology** (Scaled Agile Framework), adapted for AI agent teams.\nWorks for any team with repeatable processes: Software, Marketing, Research, Legal, Operations.\n\nIncludes:\n\n- **20 Model-Invoked Skills** - Domain expertise that loads automatically (Skills 2.0 frontmatter)\n- **24 Slash Commands** - Workflow automation for common tasks\n- **11 SAFe Agent Profiles** - Specialized roles with clear boundaries\n- **Three-Layer Architecture** - Hooks → Commands → Skills\n- **Agent Teams** - Multi-agent orchestration with SAFe quality gates (experimental)\n- **Dark Factory** - Persistent autonomous agent teams via tmux on remote servers ([guide](dark-factory/README.md))\n- **Knowledge Vault** - Evidence-verified knowledge base with a drift-detecting validator ([guide](knowledge-vault/README.md))\n\n> **Origin**: 5 months production use, 169 issues, 2,193 commits. Implements patterns from\n> [6 Anthropic engineering papers](#implementing-anthropics-research) and [SAFe methodology](https://scaledagileframework.com/).\n\n---\n\n## Quick Start (30 seconds)\n\n### Claude Code (Anthropic)\n\n```bash\n# Copy harness to your project\ncp -r .claude/ /your-project/.claude/\n\n# Customize placeholders across all provider files ({{TICKET_PREFIX}}, {{PROJECT_NAME}},\n# and the rest) in one pass:\nbash scripts/setup-template.sh\n\n# Start working\n/start-work TICKET-123\n```\n\n### Gemini CLI (Google)\n\n```bash\n# Copy harness to your project\ncp -r .gemini/ /your-project/.gemini/\n\n# Install Gemini CLI (if needed)\nnpm install -g @google/gemini-cli\n\n# Authenticate\nexport GEMINI_API_KEY=\"your-api-key\"\n\n# Start working\n/workflow:start-work TICKET-123\n```\n\n### Codex CLI (OpenAI)\n\n```bash\n# Copy harness to your project\ncp -r .codex/ /your-project/.codex/\ncp -r .agents/ /your-project/.agents/\n\n# Install Codex CLI (if needed)\nnpm install -g @openai/codex\n\n# Authenticate\nexport OPENAI_API_KEY=\"your-api-key\"\n\n# Start working (natural language, no slash commands)\ncodex\n```\n\n### Cursor IDE (Anysphere)\n\n```bash\n# Copy rules to your project\ncp -r .cursor/ /your-project/.cursor/\n\n# Open in Cursor\ncursor /your-project\n\n# Rules activate automatically based on file context\n# Use @rule-name to invoke agent roles manually\n```\n\n**That's it.** Your AI assistant now has your team's workflow patterns built in.\n\n---\n\n## Keeping Your Harness Updated\n\nAlready using the harness and a new version is out? You have two paths:\n\n**Automated** (multi-domain, manifest-based):\n```bash\n# Initialize sync metadata (first time only)\n./scripts/sync-claude-harness.sh init\n./scripts/sync-claude-harness.sh manifest init --yes\n\n# Preview and apply (syncs all domains in your manifest's sync_scope)\n./scripts/sync-claude-harness.sh sync --version v2.11.1 --dry-run\n./scripts/sync-claude-harness.sh sync --version v2.11.1\n\n# Sync specific domains only\n./scripts/sync-claude-harness.sh sync --version v2.11.1 --scope .claude,.gemini\n```\n\n**Manual** (full release, all providers):\n```bash\ngit remote add harness https://github.com/bybren-llc/safe-agentic-workflow.git\ngit fetch harness main --tags\ngit diff v2.10.0..v2.11.1 --stat # See what changed\ngit checkout harness/main -- .codex/agents/ # Cherry-pick what you need\nbash scripts/sync-claude-harness.sh --dry-run # Preview, then drop --dry-run to apply\n```\n\n> The sync script protects your customizations via a manifest (required since v2.10.0).\n> It won't overwrite files you've marked as protected. See the\n> [Harness Sync Guide](docs/HARNESS_SYNC_GUIDE.md) for the full reference and\n> [Upgrade Guide](docs/releases/v2.10.0-UPGRADE.md) for rollback options.\n\n---\n\n## The Three-Layer Architecture\n\n```text\n┌──────────────────────────────────────────────────────────────────────┐\n│ Claude Code Harness │\n├──────────────────────────────────────────────────────────────────────┤\n│ LAYER 1: HOOKS │ Automatic guardrails (format checks, blockers) │\n│ LAYER 2: COMMANDS │ User-invoked workflows (/start-work, /pre-pr) │\n│ LAYER 3: SKILLS │ Model-invoked expertise (pattern discovery) │\n└──────────────────────────────────────────────────────────────────────┘\n```\n\n> **Philosophy**: Process as _service_, not _control_.\n> Everything exists to reduce cognitive load on already-solved problems.\n\n---\n\n## Choose Your Path\n\n
\nFor Practitioners - I want to use this today\n\n### Getting Started\n\n1. Run `bash scripts/setup-template.sh` to customize placeholders\n2. Read the [Getting Started Guide](docs/guides/GETTING-STARTED.md) for the full walkthrough\n3. Run `/start-work` on your first ticket\n\n**Adopting into an existing repo?** See the [Workspace Adoption Guide](docs/guides/WORKSPACE-ADOPTION-GUIDE.md).\n**Upgrading from a previous version?** See [Keeping the Harness Updated](docs/guides/WORKSPACE-ADOPTION-GUIDE.md#keeping-the-harness-updated).\n**Syncing your fork with upstream?** See the [Harness Sync Guide](docs/HARNESS_SYNC_GUIDE.md).\n**Planning a multi-issue program?** See the [SAFe x AI-DLC Methodology](docs/guides/SAFE-AI-DLC-METHODOLOGY.md).\n**Building a knowledge base?** See the [Knowledge Vault](knowledge-vault/README.md).\n\n### Key Commands\n\n| Command | Purpose |\n| ----------------- | --------------------------------- |\n| `/start-work` | Begin ticket with proper workflow |\n| `/pre-pr` | Validate before pull request |\n| `/end-work` | Complete session cleanly |\n| `/check-workflow` | Quick status check |\n\n### Full Command Reference\n\n**Workflow** (8): `/start-work`, `/pre-pr`, `/release`, `/end-work`, `/check-workflow`, `/update-docs`, `/retro`, `/sync-linear`\n\n**Local Operations** (3): `/local-sync`, `/local-deploy`, `/quick-fix`\n\n**Remote Operations** (5): `/remote-status`, `/remote-deploy`, `/remote-health`, `/remote-logs`, `/remote-rollback`\n\n[Complete Setup Guide](.claude/SETUP.md)\n\n
\n\n
\nFor Researchers - I want to understand the methodology\n\n### Research Foundation\n\nThis harness implements patterns from 6 Anthropic engineering papers (see [below](#implementing-anthropics-research)).\n\nSee `docs/whitepapers/` for methodology deep-dives and comparative analysis.\n\n
\n\n
\nFor Leaders - I want to understand adoption\n\n### Adoption Requirements\n\n- At least one supported AI tool: Claude Code, Gemini CLI, Codex CLI, or Cursor IDE\n- Git repository\n- Team buy-in for structured workflows\n\n### Why Teams Choose SAW\n\n- **Structured autonomy**: AI agents work within clear boundaries and quality gates\n- **Evidence-based delivery**: Every deliverable requires verifiable evidence, not \"trust me\"\n- **Stop-the-line authority**: Any agent can halt work for quality or security concerns\n- **Multi-provider flexibility**: Same workflow across Claude Code, Gemini CLI, Codex CLI, and Cursor IDE\n\n### Known Limitations\n\n- Claude Code has the deepest integration; Gemini CLI, Codex CLI, and Cursor IDE support is newer\n- Non-SWE domain adaptations (marketing, research) are documented but not yet validated in production\n\n
\n\n---\n\n## Gemini CLI Integration\n\n
\nWhy Gemini CLI? - Unique capabilities and when to use it\n\n### Gemini CLI Unique Features\n\nGemini CLI offers capabilities that complement Claude Code:\n\n| Feature | Gemini CLI | Claude Code |\n|---------|------------|-------------|\n| **Shell Injection** | `!{command}` - Execute shell, inject output into prompt | Via Bash tool only |\n| **File Injection** | `@{file}` - Inject file contents into prompts | Via Read tool only |\n| **Built-in Sandbox** | Google Cloud sandboxing | MCP sandboxing |\n| **Model Options** | Gemini 3 Flash, Gemini 3.1 Pro Preview | Claude Opus, Sonnet, Haiku |\n| **Command Format** | TOML | YAML + Markdown |\n| **Namespaced Commands** | `/workflow:start-work` | `/start-work` |\n| **Hooks** | `settings.json` hooks section | `hooks-config.json` |\n| **MCP Servers** | `settings.json` mcpServers | `settings.local.json` |\n| **Hook Migration** | `gemini hooks migrate --from-claude` | N/A |\n| **Plan Mode** | `/plan` command, plan-then-execute | N/A |\n| **Policy Engine** | YAML policies, seatbelt profiles | N/A |\n| **Browser Agent** | Built-in experimental agent | MCP (claude-in-chrome) |\n| **Extensions** | Bundled skill/MCP/command packages | N/A |\n| **Checkpointing** | `/restore` session recovery | N/A |\n| **Audio/Video** | Native multimodal (Gemini 3+) | N/A |\n\n### When to Use Gemini CLI\n\n**Choose Gemini CLI when you need:**\n- Shell command output directly in prompts (`!{git log --oneline -5}`)\n- File contents injected into context (`@{package.json}`)\n- Plan mode for complex multi-step tasks (`/plan`)\n- Audio/video transcription and analysis (Gemini 3+ multimodal)\n- Policy engine for fine-grained tool control\n- Google Cloud integration and Gemini model family access\n\n**Choose Claude Code when you need:**\n- Agent subprocesses with tool restrictions\n- Claude model family access\n- Production-tested workflow (5+ months validated)\n\n### Gemini CLI Quick Reference\n\n```bash\n# Installation\nnpm install -g @google/gemini-cli\n\n# Authentication (choose one)\nexport GEMINI_API_KEY=\"your-api-key\"\n# or\ngcloud auth application-default login\n\n# Start Gemini CLI\ngemini\n\n# List available commands\n/help\n\n# List available skills\n/skills\n```\n\n### Command Syntax Differences\n\n| Action | Claude Code | Gemini CLI |\n|--------|-------------|------------|\n| Start work | `/start-work {{TICKET_PREFIX}}-123` | `/workflow:start-work {{TICKET_PREFIX}}-123` |\n| Pre-PR check | `/pre-pr` | `/workflow:pre-pr` |\n| Local sync | `/local-sync` | `/local:sync` |\n| Remote deploy | `/remote-deploy` | `/remote:deploy` |\n| Search patterns | `/search-pattern \"pattern\"` | `/search-pattern \"pattern\"` |\n\n### Gemini CLI Documentation\n\n- **Official Docs**: [geminicli.com](https://geminicli.com)\n- **Installation**: [geminicli.com/docs/get-started/installation/](https://geminicli.com/docs/get-started/installation/)\n- **Authentication**: [geminicli.com/docs/get-started/authentication/](https://geminicli.com/docs/get-started/authentication/)\n- **Custom Commands**: [geminicli.com/docs/cli/custom-commands/](https://geminicli.com/docs/cli/custom-commands/)\n- **Skills**: [geminicli.com/docs/cli/skills/](https://geminicli.com/docs/cli/skills/)\n\n
\n\n---\n\n## Implementing Anthropic's Research\n\nThis harness directly implements patterns from Anthropic's engineering papers:\n\n| Paper | What We Implement |\n| ----------------------------------------------------------------------------------------------------------- | -------------------------- |\n| [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) | 11-agent team structure |\n| [Effective Harnesses](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) | Three-layer architecture |\n| [Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) | 20 model-invoked skills |\n| [Skills Announcement](https://www.anthropic.com/news/skills) | Skills 2.0 frontmatter, trigger patterns |\n| [Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) | Tool restrictions per role |\n\n> \"The best harness is one you forget exists.\" — [Agent Perspective](docs/whitepapers/CLAUDE-CODE-HARNESS-AGENT-PERSPECTIVE.md)\n\n---\n\n## SAFe Foundation\n\n
\nFor Agile Practitioners - Deep dive into SAFe integration\n\nThis harness maps SAFe roles to AI agents:\n\n| SAFe Role | Agent | Responsibility |\n| ------------------------ | ---------------- | --------------------------------- |\n| Business Systems Analyst | BSA | Requirements, acceptance criteria |\n| System Architect | System Architect | Architecture decisions, ADRs |\n| Product Owner | POPM (human) | Final approval on deliverables |\n| Scrum Master | TDM | Coordination, blocker escalation |\n| Release Train Engineer | RTE | CI/CD, release coordination |\n\n### SAFe Concepts Implemented\n\n- **Epic → Feature → Story → Enabler** hierarchy in specs\n- **Sprint cycles** with velocity tracking (or **Bolts** — see below)\n- **Evidence-based delivery** with Linear integration\n- **Specs-driven workflow** - BSA plans, developers execute\n\n\n
\n\n---\n\n## Program Cadence: SAFe x AI-DLC\n\nSAFe gives this harness its structure. But SAFe's _cadence_ assumes human squads on week-long\nsprints, and agent teams do not move at that speed — a team of specialized agents can elaborate,\nbuild, and verify a unit of work in hours.\n\nSo the harness also ships the **SAFe x AI-DLC fusion**: SAFe keeps the hierarchy, WSJF, role\nboundaries, and Definition of Done; [AWS's AI-Driven Development Life Cycle](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/)\nsupplies the cadence and the human checkpoint. **In a program that adopts the fusion, the Bolt takes\nthe sprint's place.** Adoption is per-program; the standard sprint path stays valid.\n\nInside such a program, each concept below stands in for its SAFe counterpart:\n\n| Concept | Stands in for | Definition |\n| --- | --- | --- |\n| **Bolt** | The sprint | An hours-to-days swarm with an entry gate and a hard exit. Exits on evidence, not a date. |\n| **Unit of Work** | The Feature | One coherent outcome. A project in the tracker. |\n| **Mob Elaboration** | Sprint planning | Decompose, list unknowns, ask questions — **before** writing any code. |\n| **The loop** | The stand-up | AI plans → AI asks → **human validates business context** → AI executes. |\n\nThe human validation step is not optional. Agents own the build; humans own the judgment — secrets,\nsecurity policy, branch protection, risk thresholds, and signing the Definition of Done always route\nto a human with options and a recommendation.\n\n### Using It\n\n| Resource | Purpose |\n| --- | --- |\n| [Methodology guide](docs/guides/SAFE-AI-DLC-METHODOLOGY.md) | Read this first — vocabulary, worked example, when **not** to use a Bolt |\n| `safe-ai-dlc` skill | The method encoded for agents (Claude, Gemini, portable; Cursor as a rule) |\n| [Program template](specs_templates/program_template.md) | Scaffolding for a new program document |\n| `linear-sop` skill | Program structure: initiative → project → milestone → issue |\n\nUse it when work spans **many issues and needs cadence** — turning an audit, epic, or initiative into\nan executable program. For a single ticket, the standard `safe-workflow` path is correct. And if the\nproblem space is still unclear, run a **spike** instead: forcing an ambiguous epic into one Bolt just\nrelocates the ambiguity into the code.\n\n---\n\n## Knowledge Vault\n\nAgent teams need a shared map of the system, and a map nobody can prove is current will quietly\nbecome wrong. The `knowledge-vault/` subsystem is an **evidence-verified knowledge base**: every\nconcept records the commit its claims were checked against, so staleness is something you\n**compute**, not something you feel.\n\nBuilt on [Open Knowledge Format v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)\n(Google, Apache-2.0), which gives portability. This harness adds the rigor layer that gives trust:\na strict frontmatter contract, a zero-dependency validator, an anti-hallucination link rule, and a\ndrift mechanism.\n\nIn the project this method came from, an independent architecture audit called the vault _\"the\nsingle strongest KT asset in the repo\"_ and told new developers to trust it **over** the project's\nown canonical context file — because the vault's claims were verified against a SHA and the\ncanonical file's had silently drifted.\n\n### Run It\n\n| Prompt | Who it is for |\n| --- | --- |\n| [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. |\n| [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. |\n\n```bash\n# Prove the tooling works before you trust it\nnode knowledge-vault/scripts/validate-vault.mjs --vault knowledge-vault/templates/starter-bundle\n```\n\n| Resource | Purpose |\n| --- | --- |\n| [Knowledge Vault README](knowledge-vault/README.md) | Start here — 30-second quickstart |\n| [Guide](knowledge-vault/docs/GUIDE.md) | The method, and why each rule exists |\n| [Adoption Playbook](knowledge-vault/docs/ADOPTION-PLAYBOOK.md) | Steps, taxonomy choice, CI gating, ticket breakdown |\n| [Obsidian Guide](knowledge-vault/docs/OBSIDIAN-GUIDE.md) | Graph, canvases, Bases, and the config treaty |\n| `vault-sync` skill | Drift detection and repair (Claude, Gemini, portable; Cursor as a rule) |\n\n### The reading layer\n\nBecause an OKF bundle is a directory of plain markdown, **Obsidian opens it with no conversion\nstep**, and that is where the vault stops feeling like a docs folder: a **graph view** of the\nconcept graph (colour-grouped by directory, with orphans deliberately visible because an orphan is\na defect), **canvases** for relationships a linear document cannot show, and **Bases** saved\nqueries including a drift dashboard listing every concept whose `verified_against` has fallen\nbehind. `knowledge-vault/templates/obsidian/` ships the app, graph and core-plugin config; the\ncanvases and Bases views ship inside the vault itself. Bases needs Obsidian 1.9+.\n\nObsidian is not required: no community plugins are needed, and the vault degrades to plain markdown\nin any editor. But the graph, canvases and dashboard are a large part of what you get.\n\n---\n\n## The 11-Agent Team\n\n| Agent | Role | When to Use |\n| ----------------- | ----------------------- | ------------------------- |\n| BSA | Requirements & specs | Starting any feature |\n| System Architect | Architecture review | Significant changes |\n| FE Developer | Frontend implementation | UI components |\n| BE Developer | Backend implementation | API routes, server logic |\n| Data Engineer | Database & migrations | Schema changes |\n| QAS | Quality assurance | Test validation |\n| Security Engineer | Security validation | RLS, vulnerability checks |\n| Tech Writer | Documentation | Guides, technical content |\n| DPE | Data provisioning | Test data, seeds |\n| RTE | Release coordination | CI/CD, deployments |\n| TDM | Coordination | Blockers, escalation |\n\nSee [AGENTS.md](AGENTS.md) for complete reference with invocation examples.\n\n---\n\n## Domain Adaptation Guide\n\nThe harness patterns work beyond software engineering:\n\n### Marketing Team Example\n\n| SWE Concept | Marketing Adaptation |\n| --------------- | --------------------- |\n| BSA (specs) | Campaign Brief Writer |\n| Code Review | Asset Review |\n| `/pre-pr` | `/pre-launch` |\n| Pattern Library | Brand Guidelines |\n\n### Research Team Example\n\n| SWE Concept | Research Adaptation |\n| ------------- | -------------------- |\n| User Stories | Research Questions |\n| Test Cases | Validation Criteria |\n| CI/CD | Peer Review Pipeline |\n| Documentation | Literature Notes |\n\n---\n\n## What Makes This Different\n\n### Round Table Philosophy\n\nHuman and AI input have equal weight. No hierarchy, just expertise.\n\n### Stop-the-Line Authority\n\nAny agent can halt work for architectural or security concerns.\n\n### Pattern Discovery Protocol\n\n\"Search First, Reuse Always, Create Only When Necessary\"\n\n### Evidence-Based Delivery\n\nAll work requires verifiable evidence. No \"trust me, it works.\"\n\n---\n\n## vNext Workflow Contract (v1.4)\n\n> **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.\n\n### Complete Agent Flow\n\n```\n┌─────────────────────────────────────────────────────────────────────────────────────────┐\n│ SAFe AGENTIC WORKFLOW - vNext │\n└─────────────────────────────────────────────────────────────────────────────────────────┘\n\n ┌──────────────┐\n │ USER/POPM │\n │ Creates │\n │ Linear │\n │ Ticket │\n └──────┬───────┘\n │\n ▼\n ┌────────────────────────┐\n │ BSA │\n │ • Defines AC/DoD │\n │ • Pattern discovery │\n │ • Creates spec │\n └────────────┬───────────┘\n │\n ┌──────────────────┴──────────────────┐\n │ STOP-THE-LINE GATE │\n │ AC/DoD exists? YES → Proceed │\n │ NO → STOP │\n └──────────────────┬──────────────────┘\n │\n ┌──────────────────────┼──────────────────────┐\n ▼ ▼ ▼\n ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐\n │ BE-DEVELOPER │ │ FE-DEVELOPER │ │ DATA-ENGINEER │\n │ Exit: \"Ready │ │ Exit: \"Ready │ │ Exit: \"Ready │\n │ for QAS\" │ │ for QAS\" │ │ for QAS\" │\n └────────┬────────┘ └────────┬────────┘ └────────┬────────┘\n └──────────────────────┼──────────────────────┘\n ▼\n ┌─────────────────────────────────┐\n │ QAS (GATE OWNER) │\n │ • Iteration authority │\n │ • Bounce back repeatedly │\n │ • Final evidence to Linear │\n │ Exit: \"Approved for RTE\" │\n └────────────┬────────────────────┘\n ▼\n ┌─────────────────────────────────┐\n │ RTE (PR SHEPHERD) │\n │ • PR creation (from spec) │\n │ • CI/CD monitoring │\n │ • NO code, NO merge │\n │ Exit: \"Ready for HITL Review\" │\n └────────────┬────────────────────┘\n ▼\n ┌─────────────────────────────────────────────┐\n │ 3-STAGE PR REVIEW │\n │ Stage 1: System Architect (pattern) │\n │ Stage 2: ARCHitect-in-CLI (architecture) │\n │ Stage 3: HITL ({{AUTHOR_NAME}}) → MERGE │\n └─────────────────────────────────────────────┘\n```\n\n### Exit States\n\n```\n┌─────────────────┬───────────────────────────────────────────┐\n│ Role │ Exit State │\n├─────────────────┼───────────────────────────────────────────┤\n│ BE-Developer │ \"Ready for QAS\" │\n│ FE-Developer │ \"Ready for QAS\" │\n│ Data-Engineer │ \"Ready for QAS\" │\n│ QAS │ \"Approved for RTE\" │\n│ RTE │ \"Ready for HITL Review\" │\n│ System Architect│ \"Stage 1 Approved - Ready for ARCHitect\" │\n│ HITL │ MERGED │\n└─────────────────┴───────────────────────────────────────────┘\n```\n\n### Gate Quick Reference\n\n```\n┌─────────────────┬─────────────────┬─────────────────────────┐\n│ Gate │ Owner │ Blocking? │\n├─────────────────┼─────────────────┼─────────────────────────┤\n│ Stop-the-Line │ Implementer │ YES - no AC = no work │\n│ QAS Gate │ QAS │ YES - no approval = stop│\n│ Stage 1 Review │ System Architect│ YES - pattern check │\n│ Stage 2 Review │ ARCHitect-CLI │ YES - architecture check│\n│ HITL Merge │ {{AUTHOR_NAME}} │ YES - final authority │\n└─────────────────┴─────────────────┴─────────────────────────┘\n```\n\n### Role Collapsing ({{TICKET_PREFIX}}-499)\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ ROLE COLLAPSING AUTHORITY │\n├─────────────────────────────────────────────────────────────┤\n│ │\n│ COLLAPSIBLE: │\n│ ┌─────────────────────────────────────────────────────┐ │\n│ │ RTE (Release Train Engineer) │ │\n│ │ • PR creation can be done by implementer │ │\n│ │ • Use when: Simple PRs, single-agent work │ │\n│ └─────────────────────────────────────────────────────┘ │\n│ │\n│ NOT COLLAPSIBLE (Independence Gates): │\n│ ┌─────────────────────────────────────────────────────┐ │\n│ │ QAS (Quality Assurance Specialist) │ │\n│ │ • ALWAYS spawn subagent - never self-review │ │\n│ │ • Rationale: Self-review bias, quality enforcement │ │\n│ ├─────────────────────────────────────────────────────┤ │\n│ │ Security Engineer │ │\n│ │ • ALWAYS spawn subagent - never self-audit │ │\n│ │ • Rationale: Security blindness, conflict of interest│ │\n│ └─────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Collapsed Workflow Example\n\n```\nStandard Workflow:\nImplementer → QAS → RTE → HITL\n │\n └─ RTE handles PR creation\n\nCollapsed Workflow (RTE collapsed):\nImplementer → QAS → [Implementer handles PR] → HITL\n │\n └─ QAS gate ALWAYS present, never collapsed\n\nNote: Quality gates are immutable. QAS and SecEng cannot be collapsed.\n```\n\n
\nPart 1: Core Workflow Architecture - Complete flow diagrams\n\n### 1.1 Complete Agent Flow (Detailed)\n\n```\n┌─────────────────────────────────────────────────────────────────────────────────────────┐\n│ SAFe AGENTIC WORKFLOW - vNext │\n└─────────────────────────────────────────────────────────────────────────────────────────┘\n\n ┌──────────────┐\n │ USER/POPM │\n │ Creates │\n │ Linear │\n │ Ticket │\n └──────┬───────┘\n │\n ▼\n ┌────────────────────────┐\n │ BSA │\n │ • Defines AC/DoD │\n │ • Pattern discovery │\n │ • Creates spec │\n └────────────┬───────────┘\n │\n ┌──────────────────┴──────────────────┐\n │ STOP-THE-LINE GATE │\n │ ┌────────────────────────────────┐ │\n │ │ AC/DoD exists? │ │\n │ │ • YES → Proceed │ │\n │ │ • NO → STOP, route to BSA │ │\n │ └────────────────────────────────┘ │\n └──────────────────┬──────────────────┘\n │\n ┌──────────────────────┼──────────────────────┐\n │ │ │\n ▼ ▼ ▼\n ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐\n │ BE-DEVELOPER │ │ FE-DEVELOPER │ │ DATA-ENGINEER │\n │ │ │ │ │ │\n │ Owns: │ │ Owns: │ │ Owns: │\n │ • API routes │ │ • UI components│ │ • Schema/DB │\n │ • Server logic │ │ • Client logic │ │ • Migrations │\n │ • SAFe commits │ │ • SAFe commits │ │ • SAFe commits │\n │ │ │ │ │ │\n │ Must NOT: │ │ Must NOT: │ │ Must NOT: │\n │ • Create PRs │ │ • Create PRs │ │ • Create PRs │\n │ • Merge │ │ • Merge │ │ • Merge │\n │ │ │ │ │ • Skip ARCHitect│\n └────────┬────────┘ └────────┬────────┘ └────────┬────────┘\n │ │ │\n │ Exit: \"Ready for QAS\" │\n └──────────────────────┼──────────────────────┘\n │\n ▼\n ┌─────────────────────────────────┐\n │ QAS │\n │ (GATE OWNER) │\n │ │\n │ Powers: │\n │ • Iteration authority │\n │ • Bounce back repeatedly │\n │ • Route to specialists │\n │ • Final evidence to Linear │\n │ │\n │ Tools (Linear MCP): │\n │ • mcp__{{MCP_LINEAR_SERVER}}__ │\n │ create_comment │\n │ • mcp__{{MCP_LINEAR_SERVER}}__ │\n │ update_issue │\n │ • mcp__{{MCP_LINEAR_SERVER}}__ │\n │ list_comments │\n └────────────┬────────────────────┘\n │\n ┌────────────────┴────────────────┐\n │ │\n ▼ ▼\n ┌─────────────────┐ ┌─────────────────┐\n │ BLOCKED │ │ APPROVED │\n │ │ │ │\n │ Routes to: │ │ Exit State: │\n │ • Implementer │ │ \"Approved │\n │ • Tech Writer │ │ for RTE\" │\n │ • Sys Architect│ │ │\n └────────┬────────┘ └────────┬────────┘\n │ │\n │ (Loop until fixed) │\n └──────────────────────────────────┤\n │\n ▼\n ┌─────────────────────────────────┐\n │ RTE │\n │ (PR SHEPHERD) │\n │ │\n │ Owns: │\n │ • PR creation (from spec) │\n │ • CI/CD monitoring │\n │ • Evidence assembly │\n │ • PR metadata edits │\n │ │\n │ Must NOT: │\n │ • Write product code │\n │ • Merge PRs │\n │ • Approve own work │\n └────────────┬────────────────────┘\n │\n ▼\n ┌─────────────────────────────────────────────┐\n │ 3-STAGE PR REVIEW │\n │ │\n │ ┌─────────────────────────────────────┐ │\n │ │ STAGE 1: System Architect │ │\n │ │ • Pattern compliance │ │\n │ │ • RLS enforcement │ │\n │ │ • Technical validation │ │\n │ │ → Exit: \"Stage 1 Approved\" │ │\n │ └─────────────────┬───────────────────┘ │\n │ ▼ │\n │ ┌─────────────────────────────────────┐ │\n │ │ STAGE 2: ARCHitect-in-CLI │ │\n │ │ • Comprehensive review │ │\n │ │ • Architecture validation │ │\n │ │ • Security verification │ │\n │ │ → Exit: \"Stage 2 Approved\" │ │\n │ └─────────────────┬───────────────────┘ │\n │ ▼ │\n │ ┌─────────────────────────────────────┐ │\n │ │ STAGE 3: HITL ({{AUTHOR_NAME}}) │ │\n │ │ • Final human review │ │\n │ │ • Merge authority │ │\n │ │ → Action: MERGE │ │\n │ └─────────────────────────────────────┘ │\n └─────────────────────────────────────────────┘\n```\n\n### 1.2 Exit States Flow (with Handoff Statements)\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ EXIT STATE PROGRESSION │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n IMPLEMENTATION QAS RTE HITL\n ───────────── ───── ───── ──────\n\n ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n │ Coding │ │ Validating │ │ Shepherding│ │ Reviewing │\n │ Testing │ │ Iterating │ │ CI/CD │ │ Merging │\n │ Commits │ │ Evidence │ │ Assembling │ │ │\n └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘\n │ │ │ │\n ▼ ▼ ▼ ▼\n ╔═════════════╗ ╔═════════════╗ ╔═════════════╗ ╔═════════════╗\n ║ \"Ready ║ ────▶ ║ \"Approved ║ ────▶ ║ \"Ready for ║ ──▶ ║ MERGED ║\n ║ for QAS\" ║ ║ for RTE\" ║ ║ HITL Review\"║ ║ ║\n ╚═════════════╝ ╚═════════════╝ ╚═════════════╝ ╚═════════════╝\n │ │ │\n │ │ │\n ▼ ▼ ▼\n ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n │ Handoff │ │ Handoff │ │ Handoff │\n │ Statement: │ │ Statement: │ │ Statement: │\n │ │ │ │ │ │\n │ \"BE/FE/DE │ │ \"QAS valid- │ │ \"PR #XXX │\n │ impl done │ │ ation done │ │ ready for │\n │ for {{TICKET_PREFIX}}-X. │ │ for {{TICKET_PREFIX}}-X. │ │ HITL review.│\n │ All valid- │ │ All PASSED. │ │ CI green, │\n │ ation pass. │ │ Approved │ │ reviews │\n │ AC/DoD │ │ for RTE.\" │ │ complete.\" │\n │ confirmed. │ │ │ │ │\n │ Ready for │ │ │ │ │\n │ QAS.\" │ │ │ │ │\n └─────────────┘ └─────────────┘ └─────────────┘\n```\n\n### 1.3 Stop-the-Line Gate (Mandatory)\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ STOP-THE-LINE GATE (MANDATORY) │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n ┌─────────────────┐\n │ TICKET ARRIVES │\n │ (Linear {{TICKET_PREFIX}}-X) │\n └────────┬────────┘\n │\n ▼\n ┌─────────────────────────┐\n │ CHECK: AC/DoD EXISTS? │\n └────────────┬────────────┘\n │\n ┌─────────────────┴─────────────────┐\n │ │\n ▼ ▼\n ┌─────────────────┐ ┌─────────────────┐\n │ YES │ │ NO │\n │ │ │ │\n │ AC/DoD is │ │ AC/DoD missing │\n │ defined and │ │ or unclear │\n │ clear │ │ │\n └────────┬────────┘ └────────┬────────┘\n │ │\n ▼ ▼\n ┌─────────────────┐ ╔═════════════════╗\n │ PROCEED │ ║ FULL STOP ║\n │ │ ║ ║\n │ Begin │ ║ • Do NOT ║\n │ implementation │ ║ proceed ║\n │ │ ║ ║\n │ │ ║ • Route back ║\n │ │ ║ to BSA/POPM ║\n │ │ ║ ║\n │ │ ║ • You are NOT ║\n │ │ ║ responsible ║\n │ │ ║ for inventing║\n │ │ ║ AC/DoD ║\n └─────────────────┘ ╚═════════════════╝\n\n\n ┌───────────────────────────────────────────────────────────────────────────┐\n │ POLICY: Implementation agents (BE/FE/DE) must verify AC/DoD exists │\n │ before starting ANY work. This is a hard gate, not optional. │\n └───────────────────────────────────────────────────────────────────────────┘\n```\n\n### 1.4 QAS Iteration Loop\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ QAS ITERATION AUTHORITY │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n ┌─────────────────┐\n │ WORK ARRIVES │\n │ \"Ready for QAS\"│\n └────────┬────────┘\n │\n ▼\n ┌─────────────────────────┐\n │ QAS VALIDATES WORK │\n │ │\n │ • Run test suites │\n │ • Check AC/DoD │\n │ • Verify evidence │\n │ • Review documentation │\n └────────────┬────────────┘\n │\n ┌─────────────────┴─────────────────┐\n │ │\n ▼ ▼\n ┌─────────────────┐ ┌─────────────────┐\n │ ALL PASS ✓ │ │ ISSUES FOUND │\n │ │ │ │\n │ • Tests pass │ │ • Tests fail │\n │ • AC/DoD met │ │ • AC incomplete│\n │ • Evidence OK │ │ • Docs missing │\n │ • Docs match │ │ • Pattern issue│\n └────────┬────────┘ └────────┬────────┘\n │ │\n ▼ ▼\n ╔═════════════════╗ ┌─────────────────┐\n ║ APPROVED ║ │ BLOCKED │\n ║ ║ │ │\n ║ Post evidence ║ │ Route to: │\n ║ to Linear ║ │ │\n ║ ║ │ ┌───────────┐ │\n ║ Exit: \"Approved║ │ │Code bugs │──┼──▶ @be-developer\n ║ for RTE\" ║ │ └───────────┘ │ @fe-developer\n ╚═════════════════╝ │ ┌───────────┐ │\n │ │Validation │──┼──▶ Implementer\n │ │fails │ │\n │ └───────────┘ │\n │ ┌───────────┐ │\n │ │Doc gaps │──┼──▶ @tech-writer\n │ └───────────┘ │\n │ ┌───────────┐ │\n │ │Pattern │──┼──▶ @system-architect\n │ │violation │ │\n │ └───────────┘ │\n │ ┌───────────┐ │\n │ │AC/DoD │──┼──▶ @bsa\n │ │missing │ │\n │ └───────────┘ │\n └────────┬────────┘\n │\n │ (Fix and return)\n │\n ▼\n ┌─────────────────┐\n │ REPEAT UNTIL │\n │ ALL PASS │\n │ │\n │ QAS has full │\n │ iteration │\n │ authority │\n └─────────────────┘\n```\n\n
\n\n
\nPart 2: Role Definitions - Contract specifications for each role\n\n### 2.1 Role Ownership Matrix\n\n```\n┌─────────────────────────────────────────────────────────────────────────────────────────┐\n│ ROLE OWNERSHIP MATRIX │\n├─────────────────┬───────────────────────────────────────────────────────────────────────┤\n│ │ RESPONSIBILITIES │\n│ ROLE ├───────────┬───────────┬───────────┬───────────┬───────────┬──────────┤\n│ │ CODE │ COMMITS │ PR │ MERGE │ EVIDENCE │ GATE │\n├─────────────────┼───────────┼───────────┼───────────┼───────────┼───────────┼──────────┤\n│ BE-Developer │ ✓ │ ✓ │ ✗ │ ✗ │ Partial │ ✗ │\n│ FE-Developer │ ✓ │ ✓ │ ✗ │ ✗ │ Partial │ ✗ │\n│ Data-Engineer │ ✓ │ ✓ │ ✗ │ ✗ │ Partial │ ✗ │\n├─────────────────┼───────────┼───────────┼───────────┼───────────┼───────────┼──────────┤\n│ QAS │ ✗ │ ✗ │ ✗ │ ✗ │ ✓ │ ✓ │\n├─────────────────┼───────────┼───────────┼───────────┼───────────┼───────────┼──────────┤\n│ RTE │ ✗ │ Metadata │ ✓ │ ✗ │ Assembly │ ✗ │\n├─────────────────┼───────────┼───────────┼───────────┼───────────┼───────────┼──────────┤\n│ System Architect│ Review │ ✗ │ Stage 1 │ ✗ │ Review │ Stage 1 │\n│ ARCHitect-CLI │ Review │ ✗ │ Stage 2 │ ✗ │ Review │ Stage 2 │\n├─────────────────┼───────────┼───────────┼───────────┼───────────┼───────────┼──────────┤\n│ HITL ({{AUTHOR_NAME}}) │ Review │ ✗ │ Stage 3 │ ✓ │ Final │ Stage 3 │\n└─────────────────┴───────────┴───────────┴───────────┴───────────┴───────────┴──────────┘\n\nLegend:\n ✓ = Owns/Authorized\n ✗ = Not Authorized\n Partial = Captures during work, QAS collects\n Review = Read-only review authority\n Metadata = PR title, labels, body only (not code)\n Assembly = Collects from all agents\n```\n\n### 2.2 Implementation Agents Contract (BE/FE/DE)\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ IMPLEMENTATION AGENT CONTRACT │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ PRECONDITION (Mandatory Gate): │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ Verify AC/DoD exists → If missing, STOP and route to BSA/POPM │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ OWNS: MUST NOT: │\n│ ├─ Code changes ├─ Create PRs │\n│ ├─ Atomic SAFe commits ├─ Merge to dev/master │\n│ └─ Local validation └─ Invent AC/DoD │\n│ │\n│ MUST DO: │\n│ ├─ Run validation loop until ALL pass │\n│ ├─ Confirm ALL AC/DoD satisfied │\n│ ├─ Commit own work (SAFe format) │\n│ └─ Provide handoff statement │\n│ │\n│ EXIT STATE: \"Ready for QAS\" │\n│ │\n│ HANDOFF TEMPLATE: │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ \"[BE/FE/DE] implementation complete for {{TICKET_PREFIX}}-XXX. │ │\n│ │ All validation passing. AC/DoD confirmed. │ │\n│ │ Ready for QAS review.\" │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### 2.3 QAS Gate Owner Contract\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ QAS GATE OWNER CONTRACT │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ROLE: GATE (not just validator) │\n│ ─────────────────────────────── │\n│ Work does NOT proceed without QAS approval. │\n│ │\n│ OWNS: MUST NOT: │\n│ ├─ Independent verification ├─ Modify product code │\n│ ├─ Iteration authority ├─ Skip AC/DoD verification │\n│ ├─ QA artifacts └─ Approve incomplete work │\n│ └─ Final evidence to Linear │\n│ │\n│ LINEAR MCP TOOLS: │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ • mcp__{{MCP_LINEAR_SERVER}}__create_comment (post evidence) │ │\n│ │ • mcp__{{MCP_LINEAR_SERVER}}__update_issue (update status) │ │\n│ │ • mcp__{{MCP_LINEAR_SERVER}}__list_comments (read context) │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ROUTING AUTHORITY: │\n│ ┌────────────────┬──────────────────┬───────────────────────────────┐ │\n│ │ Issue Type │ Route To │ Action │ │\n│ ├────────────────┼──────────────────┼───────────────────────────────┤ │\n│ │ Code bugs │ @be/fe-developer │ Return with specific issues │ │\n│ │ Validation fail│ Implementer │ Return with failure output │ │\n│ │ Doc mismatch │ @tech-writer │ Route for documentation fix │ │\n│ │ Pattern issue │ @system-architect│ Escalate for pattern review │ │\n│ │ AC/DoD missing │ @bsa │ Cannot approve without AC │ │\n│ └────────────────┴──────────────────┴───────────────────────────────┘ │\n│ │\n│ EXIT STATE: \"Approved for RTE\" │\n│ │\n│ HANDOFF TEMPLATE: │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ \"QAS validation complete for {{TICKET_PREFIX}}-XXX. │ │\n│ │ All criteria PASSED. Evidence posted to Linear. │ │\n│ │ Approved for RTE.\" │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### 2.4 RTE PR Shepherd Contract\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ RTE PR SHEPHERD CONTRACT │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ PREREQUISITE (QAS Gate): │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ Work MUST have QAS approval (\"Approved for RTE\" status) │ │\n│ │ Evidence MUST be posted to Linear │ │\n│ │ If QAS not approved → STOP and wait │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ OWNS: MUST NOT (NEVER): │\n│ ├─ PR creation (from spec) ├─ Merge PRs (HITL only) │\n│ ├─ CI/CD monitoring ├─ Write product code │\n│ ├─ Evidence assembly ├─ Approve own work │\n│ ├─ PR metadata (title, labels, body) └─ Have merge cmd examples │\n│ └─ Coordination between agents │\n│ │\n│ IF CI FAILS: │\n│ ┌────────────────────────────┬─────────────────────────────────────┐ │\n│ │ Failure Type │ Route To │ │\n│ ├────────────────────────────┼─────────────────────────────────────┤ │\n│ │ Structural/pattern issues │ System Architect │ │\n│ │ Implementation bugs │ Original implementer (BE/FE/DE) │ │\n│ │ NEVER fix code yourself │ --- │ │\n│ └────────────────────────────┴─────────────────────────────────────┘ │\n│ │\n│ EXIT STATE: \"Ready for HITL Review\" │\n│ │\n│ HANDOFF TEMPLATE: │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ \"PR #XXX for {{TICKET_PREFIX}}-YYY is Ready for HITL Review. │ │\n│ │ All CI green, reviews complete, evidence attached. │ │\n│ │ Awaiting final merge approval from {{AUTHOR_NAME}}.\" │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### 2.5 System Architect Stage 1 Contract\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ SYSTEM ARCHITECT STAGE 1 CONTRACT │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ROLE: Stage 1 of 3-Stage PR Review Process │\n│ ─────────────────────────────────────────── │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ Stage 1: System Architect (you) - Technical/pattern validation │ │\n│ │ Stage 2: ARCHitect-in-CLI - Comprehensive review │ │\n│ │ Stage 3: HITL ({{AUTHOR_NAME}}) - Final merge authority │ │\n│ └───────────", "bytes": 60000, "sha": "31ff3b7aecb600a6b2c611903b6f62cd6d5319e4c547cc56d032e5a95bc0dd8b", "repo_slug": "bybren-llc/safe-agentic-workflow", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/skl_bybren_llc_safe_agentic_workflow_claude__4e0a7569/readme" }