diff --git a/AGENTS.md b/AGENTS.md index 753fea2..5feeae6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,6 +53,17 @@ Management (IAM) fabric and WebAuthn Passkey authority. - Follow the standardized engineering lifecycle: `tasks/plan.md` $\rightarrow$ `tasks/audit-1.md` $\rightarrow$ `tasks/do.md` $\rightarrow$ `tasks/audit-2.md`, with `tasks/debug.md` for hermetic root-cause analysis. +5. **Agent Orchestration & Black-Box Delegation:** + - **Autonomy over Tooling:** When preparing prompts or tasks for external + agents (e.g., Jules), NEVER micromanage their internal execution mechanics + or tool choices (e.g. do not prohibit or mandate specific scripting + languages). + - **Positive Final-State Delivery:** Define strict terminal Acceptance + Criteria (clean git working tree, formatted with `deno fmt`, all tests + passing) rather than negative constraints on in-flight tools. + - **DRY Instructions:** Rely on repository guideline documents (`AGENTS.md`, + `tasks/GUIDELINES.md`) by reference rather than copy-pasting operational + rules into prompts. ## 4. History & Context Link diff --git a/tasks/GUIDELINES.md b/tasks/GUIDELINES.md index 16e19f5..ecba4c3 100644 --- a/tasks/GUIDELINES.md +++ b/tasks/GUIDELINES.md @@ -84,3 +84,22 @@ objective against the existing codebase and document: The structured phases, code extraction points, or execution steps required to complete the task safely. + +## E. Multi-Agent Orchestration & Dispatching Standards + +When dispatching tasks to autonomous external agents (e.g. Jules, CI workers, +subagents): + +1. **Black-Box Delegation:** Treat the worker agent's execution loop as a black + box. Specify architectural invariants and domain rules clearly, but never + dictate or forbid specific internal tooling, helper scripts, or workflow + mechanics. +2. **Positive Final-State Delivery:** Never use negative constraints to govern + tool use. Instead, formulate unambiguous terminal Acceptance Criteria (clean + git tree, passing test suites, formatted code). +3. **Pre-Review Summary Gate:** Require worker agents to provide a concise + verification summary (modified files and test pass evidence) BEFORE + requesting code review or opening the PR. +4. **DRY Prompting:** Always reference repository guidelines (`AGENTS.md`, + `tasks/GUIDELINES.md`) instead of copy-pasting operational rules into agent + prompts. diff --git a/tasks/audit-2.md b/tasks/audit-2.md index 26c50f2..e263f59 100644 --- a/tasks/audit-2.md +++ b/tasks/audit-2.md @@ -49,7 +49,7 @@ the following block: ```text **Role:** Act as a Senior Security, Architecture & Quality Assurance Auditor. Do not modify production code or push commits during this audit session. Your sole deliverable is an objective Code Quality & Security Audit Report. -**The Scope:** [Specify target branch, recent commits, modified files, or completed task in `tasks/wip/TASK_FILENAME.md`]. +**The Scope:** [Specify target branch, recent commits, modified files, or task in `tasks/new/TASK_FILENAME.md` or `tasks/complete/TASK_FILENAME.md`]. **Your Task:** Audit the actual codebase changes against the original task specification and our system guidelines (`AGENTS.md`, `docs/`) using the 5-point implementation rubric in `tasks/audit-2.md`: diff --git a/tasks/do.md b/tasks/do.md index c798b64..3acedcb 100644 --- a/tasks/do.md +++ b/tasks/do.md @@ -9,8 +9,8 @@ This protocol defines the standard for executing an approved task from When commanded to **"tasks/do `[TASK_FILE]`"**: -1. **Move to WIP:** Move the task file from `tasks/new/` to `tasks/wip/` before - starting work. +1. **Keep in New During Work:** The task file remains in `tasks/new/` while work + is in progress. 2. **Follow the 4-Step State Machine:** - **Step 1 (Research):** Inspect the target files and verify architectural assumptions. @@ -22,8 +22,10 @@ When commanded to **"tasks/do `[TASK_FILE]`"**: - `deno task check` - `deno test --allow-all` (Run ONLY hermetic unit tests; NEVER run `deno task start` in container sandboxes). - - **Step 4 (Review & Move):** Upon all gates passing, move the task file to - `tasks/complete/YYYY-MMDD.XX.agent.type.scope.title-HHMM.md`. + - **Step 4 (Review & Move):** Upon all gates passing, move the task file + directly from `tasks/new/` to + `tasks/complete/YYYY-MMDD.XX.agent.type.scope.title-HHMM.md`. (If the + session must end without completing the task, park it in `tasks/wip/`). 3. **Commit & Sync:** Commit with standard conventional commit syntax and push to both remotes (`origin` and `gitea`). @@ -39,11 +41,21 @@ and provide the following block: **The Task:** Please review and execute the approved task plan in `[tasks/new/TASK_FILENAME.md]`. -**Directives:** -1. Follow the strict 4-step state machine (Research -> Implementation -> Quality Gates -> Review). -2. Move the task file from `tasks/new/` to `tasks/wip/` before starting, and to `tasks/complete/` upon verification. -3. Apply minimal, pure functional modifications adhering to `AGENTS.md`. -4. Run all quality gates: `deno fmt`, `deno task lint`, `deno task check`, and `deno test --allow-all`. -5. Run ONLY unit tests (`deno test --allow-all`). Do NOT run `deno task start` or `deno task dev` (database daemons are not running in container sandboxes). -6. Provide a concise summary of all modified files and verified test results upon completion. +**Directives & Guidelines:** +- Adhere strictly to the repository architecture and operating protocols in `AGENTS.md` and `tasks/GUIDELINES.md`. +- Keep the task file in `tasks/new/` during execution; only move it to `tasks/complete/` upon successful verification (or park in `tasks/wip/` only if work cannot be finished in this session). +- Run ONLY hermetic unit tests (`deno test --allow-all`). Do NOT start long-running servers (`deno task start` / `deno task dev`). + +**Acceptance Criteria & Delivery Protocol:** + +1. **Pre-Review Quality & Summary (Before Requesting Review / Opening PR):** + - Run and pass all quality gates: `deno fmt`, `deno task lint`, `deno task check`, and `deno test --allow-all`. + - Ensure the git working tree contains only intentional modifications to target deliverables (zero untracked or temporary files). + - Present a concise verification summary detailing: + * Exact list of modified/created files + * Test execution results proving all test suites pass + +2. **Final Completion (Upon Approval):** + - Move the task file from `tasks/new/` directly to `tasks/complete/YYYY-MMDD.XX.agent.type.scope.title-HHMM.md` (or park in `tasks/wip/` only if work cannot be finished in this session). + - Submit the final pull request with a clean git history. ``` 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 index d59499b..fe904f5 100644 --- 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 @@ -47,8 +47,14 @@ and mechanics of the framework. 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/wip/` ──► `tasks/complete/`). + (`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.