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/
This commit is contained in:
Tyler Gillispie 2026-08-26 10:37:22 -07:00
parent 9e2cd81e4d
commit 42b336173e
5 changed files with 61 additions and 13 deletions

View File

@ -53,6 +53,17 @@ Management (IAM) fabric and WebAuthn Passkey authority.
- Follow the standardized engineering lifecycle: `tasks/plan.md` - Follow the standardized engineering lifecycle: `tasks/plan.md`
$\rightarrow$ `tasks/audit-1.md` $\rightarrow$ `tasks/do.md` $\rightarrow$ $\rightarrow$ `tasks/audit-1.md` $\rightarrow$ `tasks/do.md` $\rightarrow$
`tasks/audit-2.md`, with `tasks/debug.md` for hermetic root-cause analysis. `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 ## 4. History & Context Link

View File

@ -84,3 +84,22 @@ objective against the existing codebase and document:
The structured phases, code extraction points, or execution steps required to The structured phases, code extraction points, or execution steps required to
complete the task safely. 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.

View File

@ -49,7 +49,7 @@ the following block:
```text ```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. **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:** **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`: 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`:

View File

@ -9,8 +9,8 @@ This protocol defines the standard for executing an approved task from
When commanded to **"tasks/do `[TASK_FILE]`"**: When commanded to **"tasks/do `[TASK_FILE]`"**:
1. **Move to WIP:** Move the task file from `tasks/new/` to `tasks/wip/` before 1. **Keep in New During Work:** The task file remains in `tasks/new/` while work
starting work. is in progress.
2. **Follow the 4-Step State Machine:** 2. **Follow the 4-Step State Machine:**
- **Step 1 (Research):** Inspect the target files and verify architectural - **Step 1 (Research):** Inspect the target files and verify architectural
assumptions. assumptions.
@ -22,8 +22,10 @@ When commanded to **"tasks/do `[TASK_FILE]`"**:
- `deno task check` - `deno task check`
- `deno test --allow-all` (Run ONLY hermetic unit tests; NEVER run - `deno test --allow-all` (Run ONLY hermetic unit tests; NEVER run
`deno task start` in container sandboxes). `deno task start` in container sandboxes).
- **Step 4 (Review & Move):** Upon all gates passing, move the task file to - **Step 4 (Review & Move):** Upon all gates passing, move the task file
`tasks/complete/YYYY-MMDD.XX.agent.type.scope.title-HHMM.md`. 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 3. **Commit & Sync:** Commit with standard conventional commit syntax and push
to both remotes (`origin` and `gitea`). 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]`. **The Task:** Please review and execute the approved task plan in `[tasks/new/TASK_FILENAME.md]`.
**Directives:** **Directives & Guidelines:**
1. Follow the strict 4-step state machine (Research -> Implementation -> Quality Gates -> Review). - Adhere strictly to the repository architecture and operating protocols in `AGENTS.md` and `tasks/GUIDELINES.md`.
2. Move the task file from `tasks/new/` to `tasks/wip/` before starting, and to `tasks/complete/` upon verification. - 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).
3. Apply minimal, pure functional modifications adhering to `AGENTS.md`. - Run ONLY hermetic unit tests (`deno test --allow-all`). Do NOT start long-running servers (`deno task start` / `deno task dev`).
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). **Acceptance Criteria & Delivery Protocol:**
6. Provide a concise summary of all modified files and verified test results upon completion.
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.
``` ```

View File

@ -47,8 +47,14 @@ and mechanics of the framework.
another agent). another agent).
- **Strict Operating Gates:** The mandatory read-only first pass, dual-level - **Strict Operating Gates:** The mandatory read-only first pass, dual-level
deliberation, and explicit user approval before code edits. 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 - **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 - **Semantic Task Metadata:** The strict naming schema and mandatory
`# TASK METADATA` header. `# TASK METADATA` header.