diff --git a/tasks/new/2026-0825.01.jul.story.protocol.universal-agent-framework-1945.md b/tasks/new/2026-0825.01.jul.story.protocol.universal-agent-framework-1945.md new file mode 100644 index 0000000..d59499b --- /dev/null +++ b/tasks/new/2026-0825.01.jul.story.protocol.universal-agent-framework-1945.md @@ -0,0 +1,79 @@ +# 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.