Tyler Gillispie 42b336173e docs(protocol): enshrine black-box delegation and pre-review summary gate

- Add Section 3.5 to AGENTS.md for agent orchestration and tool autonomy
- Add Section E to tasks/GUIDELINES.md with pre-review summary gate
- Update tasks/do.md dispatch template with DRY positive acceptance criteria
- Align task lifecycle state machine to keep in-flight work in tasks/new/

2026-08-26 10:37:22 -07:00

3.9 KiB

Raw Blame History

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.
- Orchestration Axioms: Black-Box Delegation (decoupling architectural invariants from execution mechanics), Positive Final-State Delivery (mandating clean terminal git states rather than tool restrictions), and DRY Prompting.
- Kanban State Machine: The directory progression for tracking state (tasks/new/ ──► tasks/complete/, with tasks/wip/ reserved strictly as an incomplete session parking lot; files are moved only at the end of a session).
- 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.

3.9 KiB Raw Blame History