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.