auth-yes/tasks/new/2026-0825.01.jul.story.protocol.universal-agent-framework-1945.md

TASK METADATA

• Target Files: docs/MULTI_AGENT_ORCHESTRATION_FRAMEWORK.md, template/tasks/, template/AGENTS.md, template/README-widgets.md
• Core Objective: Extract and formalize the Auth-Yes multi-agent orchestration workflow into a clean, reusable, repository-agnostic blueprint and template bundle.
• Dependencies: None.
• Additional Important Notes: This task must strictly decouple Auth-Yes runtime specifics (Deno, Rust, Valkey, ConnectRPC, Postgres) from the universal meta-process lifecycle.

---

2. Architectural Considerations & Risks

• Risks:
  • Over-specialization: The framework might inadvertently retain Auth-Yes specific terminology or technology assumptions, making it hard to adopt in non-TypeScript or non-monorepo environments (e.g., Python, Go).
  • Tooling Overhead: If the bootstrap template is too complex, developers might ignore it. The template bundle needs to be lightweight and purely markdown/process-driven.
• Alternatives:
  • Instead of a manual template bundle, we could create an automated CLI (e.g., an npm/npx or Deno script) to scaffold the framework. However, a pure markdown template bundle is more universal and easier to audit initially. We will stick with the documentation and template bundle as the primary deliverable for maximum portability.

3. Proposed Implementation

This task requires creating a two-tier deliverable to formalize the Multi-Agent Development & Ideation Protocol:

Phase 1: Foundational Architecture Guide

Draft a comprehensive standalone guide (docs/MULTI_AGENT_ORCHESTRATION_FRAMEWORK.md) that documents the philosophy and mechanics of the framework.

• Universal Core Mechanics to Document:
  • 4-Step Engineering Lifecycle: The sequential pipeline (plan ──► audit-1 ──► do ──► audit-2) and the out-of-band debug protocol.
  • Dual-Mode Communication Pattern: The taxonomy of Direct Execution Protocol (acting as the agent) vs. Dispatch Template (preparing a prompt for another agent).
  • Strict Operating Gates: The mandatory read-only first pass, dual-level deliberation, and explicit user approval before code edits.
  • Kanban State Machine: The directory progression for tracking state (tasks/new/ ──► tasks/wip/ ──► tasks/complete/).
  • Semantic Task Metadata: The strict naming schema and mandatory # TASK METADATA header.

Phase 2: Drop-in Scaffolding Template Bundle

Create a clean, reusable folder structure (template/) ready to be dropped into any target repository (Node, Go, Python, Rust, etc.).

• Components to Scaffold:
  • template/tasks/: A mirrored, repo-agnostic version of the Auth-Yes tasks directory, including GUIDELINES.md, path.md, plan.md, audit-1.md, do.md, audit-2.md, and debug.md.
  • template/AGENTS.md: A starter template for system guidelines, omitting Auth-Yes runtime specifics.
  • template/README-widgets.md: Markdown snippets for integrating the engineering lifecycle diagram and quick reference tables into a project's main README.

Phase 3: Decoupling and Purging "Auth-Yesisms"

During the extraction, explicitly strip all references to Auth-Yes infrastructure, including:

• Language/Runtime bindings: Deno 2, TypeScript, Rust spire_ffi, ConnectRPC, Valkey, PostgreSQL.
• Project-specific paths: sdk/, server/, ui/, scratch/.
• Domain specifics: .atyg.org wildcard cookie domains, Traefik ForwardAuth routing.