147 lines
5.4 KiB
Markdown
147 lines
5.4 KiB
Markdown
# AI Parallel Automation and Agent Orchestration
|
|
|
|
This document explains how to dispatch scheduled tasks and bounded agents. It
|
|
does not create a second Issue contract; `issue-rule.md` remains canonical for
|
|
outcome, invariants, scope, acceptance, validation, and dependencies.
|
|
|
|
## Dispatch gate
|
|
|
|
Use the smallest useful orchestration mode:
|
|
|
|
### Single writer
|
|
|
|
Default for small work, tightly coupled state changes, shared contracts, or
|
|
when isolation is unavailable. Read-only reviewers may still explore in
|
|
parallel.
|
|
|
|
### Parallel read
|
|
|
|
Use for architecture mapping, Provider DOM investigation, security/manifest
|
|
audits, dependency analysis, test-gap discovery, or PR review.
|
|
|
|
### Isolated parallel write
|
|
|
|
Use only when write domains are independent, ownership is explicit, shared
|
|
hotspots have one writer, and each writer has a real branch/worktree or other
|
|
filesystem isolation. An integration owner and a composition path must be
|
|
known before starting.
|
|
|
|
```text
|
|
small or coupled → single writer
|
|
independent research → parallel read + single writer
|
|
independent writes → isolated writers + integration owner
|
|
uncertain ownership → single writer + review
|
|
```
|
|
|
|
## Shared hotspots
|
|
|
|
Treat these as semantic conflict domains even when files do not overlap:
|
|
|
|
- provider catalog, ProviderId taxonomy, and adapter contract;
|
|
- messaging payloads and bridge allowlists;
|
|
- workspace/provider state and request lifecycle;
|
|
- storage keys, schema, and migration behavior;
|
|
- manifest, host permissions, CSP, DNR, and release configuration;
|
|
- `package.json`, lockfiles, `.github/workflows/**`, and shared test/browser
|
|
configuration.
|
|
|
|
One wave has one writer for each shared hotspot. Provider-specific adapter work
|
|
can run independently only when the shared contract is stable and the adapter
|
|
does not change permissions, messaging, storage, or shared DOM semantics.
|
|
|
|
## Scheduled task lanes
|
|
|
|
A scheduled task is a durable ownership lane, not a timer around a tiny Issue.
|
|
Use no more than five active project automations by default; this is a safety
|
|
ceiling, not a utilization target.
|
|
|
|
Each lane must have:
|
|
|
|
- an owner and stable domain;
|
|
- a useful recurrence and a clear lane-level stop condition;
|
|
- a resume/idempotency rule that re-reads the latest Issue, `main`, PRs, and
|
|
dependencies;
|
|
- a known integration owner when it crosses a shared contract;
|
|
- focused acceptance and validation evidence.
|
|
|
|
At every run, skip already-complete work, refresh the Execution Base, select the
|
|
highest-priority unblocked work in the lane, advance to a coherent checkpoint,
|
|
validate it, and record a handoff. Stop when the lane is complete, blocked by a
|
|
specific dependency, enters unresolved scope drift, needs a product/security
|
|
decision, or the next item is a distinct review/rollback unit.
|
|
|
|
## Scheduled task prompt
|
|
|
|
```text
|
|
Repository: CoderLambert/ai-parallel
|
|
Issue(s): <numbers or none>
|
|
Lane: <stable ownership domain>
|
|
|
|
Before execution:
|
|
- Read AGENTS.md, issue-rule.md, and relevant architecture docs.
|
|
- Refresh the latest Issue, decisions, main, PRs, and dependencies.
|
|
- Establish the current Execution Base and confirm READY state.
|
|
|
|
Contract for this lane:
|
|
- Target: <relevant outcome>
|
|
- Invariants: <relevant boundaries>
|
|
- Expected scope: <owner-local scope>
|
|
- Sensitive/shared surfaces: <surfaces requiring coordination>
|
|
- Acceptance Criteria: <relevant criteria>
|
|
- Validation: <required evidence>
|
|
- Hard dependencies: <real blockers>
|
|
|
|
Execution:
|
|
1. Skip work that is already complete.
|
|
2. Implement only the bounded owner-local outcome.
|
|
3. Apply the Scope Drift protocol before expanding a shared contract.
|
|
4. Do not duplicate another lane's Provider, message, storage, or security path.
|
|
5. Validate and record the standard handoff.
|
|
6. Continue only while the next work remains in this lane's safe boundary.
|
|
```
|
|
|
|
Completed lanes should not remain active unless they have a defined monitoring
|
|
purpose. Do not create wait-only automation chains or repeatedly retry an
|
|
unchanged blocker.
|
|
|
|
## Parent and sub-agent contract
|
|
|
|
The parent agent consumes the latest Issue contract, chooses the dispatch mode,
|
|
owns scope drift and final integration, and maintains one interpretation of
|
|
invariants and acceptance criteria. Sub-agents should be bounded and preferably
|
|
read-only.
|
|
|
|
```text
|
|
You are a bounded sub-agent. The Issue contract is authoritative.
|
|
|
|
Repository: CoderLambert/ai-parallel
|
|
Issue/work item: <id>
|
|
Execution Base: <sha/ref>
|
|
Objective: <one bounded question or outcome>
|
|
Expected scope: <files/modules>
|
|
Sensitive/shared surfaces: <list>
|
|
Acceptance Criteria: <subset>
|
|
Validation: <subset>
|
|
Output: <evidence, patch, or review result>
|
|
|
|
Rules:
|
|
- Stay inside the assigned scope.
|
|
- Report evidence and assumptions separately.
|
|
- Stop and report Scope Drift before changing a shared/core contract.
|
|
- Do not modify another lane's owned scope.
|
|
- Return concise findings to the parent/integration owner.
|
|
```
|
|
|
|
## Handoff and integration
|
|
|
|
Every handoff should identify Issue, lane, Execution Base, branch/PR, HEAD,
|
|
owned scope, changed files, acceptance status, validation, security/permission
|
|
delta, risks, blockers, and next action. Do not conflate branch HEAD with the
|
|
commit actually validated by CI.
|
|
|
|
Integration is a deliberate step: refresh the candidate, inspect semantic
|
|
conflicts, review manifest/permission and storage changes, run the risk-
|
|
appropriate repository/browser checks, then record the merged commit on the
|
|
Issue. Closing an Issue or deleting an automation is not implied by a branch
|
|
commit alone.
|