docs(process): codify issue execution contracts
This commit is contained in:
@@ -10,6 +10,12 @@ You are the engineering agent for the AI Parallel repository:
|
||||
|
||||
Work from the user's request and the relevant GitHub Issue. Preserve the existing product boundary and keep changes focused. Do not start unrelated roadmap work unless the user explicitly authorizes an autonomous multi-issue run.
|
||||
|
||||
Detailed issue execution rules live in `issue-rule.md`. Read it before
|
||||
creating or materially changing an Issue. Read
|
||||
`docs/execution/AUTOMATION-AND-AGENT-ORCHESTRATION.md` when scheduled tasks,
|
||||
parallel agents, or cross-lane handoff are involved. These documents are
|
||||
loaded on demand so this file remains the short repository baseline.
|
||||
|
||||
## Product boundary
|
||||
|
||||
AI Parallel reuses the user's existing authenticated AI web sessions in the browser. It does not proxy provider APIs, store provider credentials, or send prompts and collected responses to an AI Parallel server.
|
||||
|
||||
@@ -0,0 +1,146 @@
|
||||
# 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.
|
||||
+184
@@ -0,0 +1,184 @@
|
||||
# AI Parallel Issue Rules
|
||||
|
||||
This document defines how Issues are created, executed, validated, handed off,
|
||||
and closed. It supplements the long-term repository rules in `AGENTS.md`.
|
||||
|
||||
## Source of truth
|
||||
|
||||
Use this order when facts disagree:
|
||||
|
||||
```text
|
||||
repository architecture and security rules
|
||||
↓
|
||||
latest Issue contract
|
||||
↓
|
||||
latest decision or scope-drift record
|
||||
↓
|
||||
working direction and historical context
|
||||
```
|
||||
|
||||
The normative Issue contract is its Target, Invariants, Execution Scope,
|
||||
Acceptance Criteria, Validation, and Dependencies. An implementation hint is
|
||||
allowed to change when evidence requires it.
|
||||
|
||||
## Issue states
|
||||
|
||||
```text
|
||||
DRAFT → READY → IN PROGRESS → DONE
|
||||
↘ BLOCKED
|
||||
↘ DEFERRED
|
||||
```
|
||||
|
||||
- `DRAFT`: still being investigated or designed.
|
||||
- `READY`: target, owner, dependencies, acceptance, and validation are clear.
|
||||
- `IN PROGRESS`: an agent or developer owns active implementation.
|
||||
- `BLOCKED`: a specific external dependency, ownership conflict, or decision
|
||||
prevents safe progress.
|
||||
- `DEFERRED`: valuable work intentionally postponed.
|
||||
- `DONE`: the verified change is in `main`; a feature branch alone is not done.
|
||||
|
||||
An Open Issue is not automatically READY.
|
||||
|
||||
## Minimum Issue contract
|
||||
|
||||
Use the smallest useful version of this structure:
|
||||
|
||||
```md
|
||||
## Execution State
|
||||
DRAFT | READY | IN PROGRESS | BLOCKED | DEFERRED
|
||||
|
||||
Observed base: main@<sha>
|
||||
Execution base: <fresh main or dependency condition>
|
||||
|
||||
## Problem
|
||||
Current user or engineering problem.
|
||||
|
||||
## Target
|
||||
Observable outcome after completion.
|
||||
|
||||
## Invariants
|
||||
- Behavior, compatibility, privacy, security, or validation boundaries.
|
||||
|
||||
## Execution Scope
|
||||
Expected:
|
||||
- Owner-local files or domains.
|
||||
|
||||
Sensitive / coordinate before expanding:
|
||||
- Shared, cross-domain, permission, security, or contract surfaces.
|
||||
|
||||
Out of scope by default:
|
||||
- Explicit exclusions.
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Observable completion conditions.
|
||||
|
||||
## Validation
|
||||
Focused:
|
||||
- Most relevant fast checks.
|
||||
|
||||
Repository / Regression:
|
||||
- Affected repository checks.
|
||||
|
||||
Browser:
|
||||
- Extension/browser flow when applicable.
|
||||
|
||||
Required CI:
|
||||
- Required checks, or N/A.
|
||||
|
||||
## Dependencies
|
||||
Hard blocked by:
|
||||
- Real blockers only.
|
||||
|
||||
Conflict / shared surfaces:
|
||||
- Files, contracts, or domains requiring coordination.
|
||||
```
|
||||
|
||||
Acceptance Criteria describe what must be true. Validation describes the
|
||||
evidence that proves it; they are not interchangeable.
|
||||
|
||||
## Execution preflight
|
||||
|
||||
Before implementation:
|
||||
|
||||
1. Read `AGENTS.md`, this document, the Issue, related decisions, and related
|
||||
PRs.
|
||||
2. Refresh `main`, dependencies, and concurrent work; record the current
|
||||
Execution Base.
|
||||
3. Confirm the Issue is READY and identify its owner domain.
|
||||
4. Confirm invariants, acceptance criteria, validation, and hard dependencies.
|
||||
5. Identify shared or sensitive surfaces before editing them.
|
||||
6. Choose one writer, read-only parallel review, or genuinely isolated
|
||||
parallel writers.
|
||||
|
||||
Observed Base records where the problem was found. Execution Base records the
|
||||
version actually used for implementation; do not use an old observation as a
|
||||
mechanical branch base.
|
||||
|
||||
## Ownership and scope drift
|
||||
|
||||
The current domains are Foundation/Build, Extension Runtime, Provider
|
||||
Adapters, Workspace UI, Popup UI, Messaging, Storage, Security/DNR/Permissions,
|
||||
Verification/CI, and Release.
|
||||
|
||||
Shared hotspots allow one writer per wave:
|
||||
|
||||
- provider catalog and public Provider contract;
|
||||
- messaging protocol and cross-context integration;
|
||||
- storage schema and migrations;
|
||||
- manifest, host permissions, CSP, DNR, and release configuration;
|
||||
- package/lock files and `.github/workflows/**`;
|
||||
- shared test or browser configuration.
|
||||
|
||||
Use this scope-drift protocol:
|
||||
|
||||
- Level A: an owner-local implementation adjustment that preserves external
|
||||
behavior; record it in the PR and continue.
|
||||
- Level B: a shared, cross-domain, security, permission, or contract change;
|
||||
pause that portion, record evidence, coordinate the writer/integration owner,
|
||||
and update the Issue before continuing.
|
||||
- Level C: a change to product outcome, provider architecture, storage
|
||||
semantics, security model, or required validation; revise the Issue or split
|
||||
a prerequisite before implementation.
|
||||
|
||||
Zero Git merge conflicts does not prove that parallel changes are semantically
|
||||
safe.
|
||||
|
||||
## Validation and closure
|
||||
|
||||
Match validation to risk:
|
||||
|
||||
| Change | Expected evidence |
|
||||
| --- | --- |
|
||||
| Documentation | references and structure |
|
||||
| Provider-local adapter | focused contract/fixture checks |
|
||||
| Workspace or popup UI | focused checks, build, browser smoke when applicable |
|
||||
| Messaging or storage | consumers, regression, and browser evidence |
|
||||
| Manifest, DNR, security, or release | generated artifact review and browser/release evidence |
|
||||
|
||||
Do not make a check pass by deleting tests, weakening assertions, hiding a
|
||||
deterministic error behind retries, or expanding permissions without evidence.
|
||||
|
||||
Issue comments should record durable state changes using `[PLAN]`, `[DECISION]`,
|
||||
`[BLOCKED]`, `[HANDOFF]`, or `[CLOSURE]`. A closure comment should include the
|
||||
merged commit, acceptance result, validation result, scope/security delta, and
|
||||
follow-ups. Close an Issue only after the verified change is on `main`.
|
||||
|
||||
## Standard handoff
|
||||
|
||||
```text
|
||||
STATUS: DONE | PARTIAL | BLOCKED
|
||||
ISSUE: <number or none>
|
||||
LANE: <owner domain>
|
||||
EXECUTION_BASE: <sha/ref>
|
||||
BRANCH: <branch>
|
||||
HEAD: <sha>
|
||||
PR: <number/url or none>
|
||||
OWNED_SCOPE: <files/modules>
|
||||
SENSITIVE_SURFACES_TOUCHED: <none or list>
|
||||
AC_STATUS: <complete or partial with evidence>
|
||||
VALIDATION: <checks and results>
|
||||
SECURITY_PERMISSION_DELTA: <none or concise description>
|
||||
KNOWN_RISKS: <none or concise list>
|
||||
BLOCKERS: <none or exact blocker>
|
||||
NEXT: <integration or follow-up action>
|
||||
```
|
||||
Reference in New Issue
Block a user