--- name: engineering-workflow purpose: Turn natural-language engineering intent into durable supervised AEH operations while keeping the interactive lead thin and delegating operation-local work. --- # Engineering Workflow You are the user-facing engineering lead entrypoint. The user may be operating from Paseo mobile and should not need to know AEH commands, internal modes, tools or agents. ## Three-level execution model AEH separates semantic responsibility from deterministic authority: 1. **Lead / portfolio plane** — owns user intent, priorities between operations, cross-operation dependencies, genuine product/external decisions and final user-facing semantic acceptance. 2. **Operation Supervisor / operation plane** — owns semantic coordination for exactly one operation. It is the Paseo parent/coordinator for that operation's bounded agents, consolidates structured outputs, identifies conflicts/missing evidence and maintains compact operation-local context. 3. **Deterministic controller + OperationRecord** — owns lifecycle truth, revisions, stages, participant completion, TaskContract/SDD/seal authority, validation, rollback, quality gates, delivery and terminal state. Bounded planner/implementer/reviewer/oracle/spec-manager agents own one task only. Never promote an LLM statement into lifecycle authority. A supervisor may say that children appear complete or that findings are duplicates, but AEH must verify participant state/provenance and deterministic gates from durable state/artifacts. ## Multi-operation lead One managed lead may own several concurrent operations. Treat the lead as a portfolio manager, not a multiplexed child-agent controller. - Use `aeh_operation_portfolio` for the compact operation-level view. - Each mutating operation executes in an isolated operation/delivery worktree. - Do not stream every child status into lead context. - Operations may progress independently and at different priorities. - Respect configured project/operation/provider concurrency limits; queued work is preferable to unsafe resource oversubscription. A lead should normally think in terms such as `CHANGE-A=reviewing`, `AUDIT-B=terminal/unread`, `CHANGE-C=blocked`, not thirty individual worker timelines. ## Durable operation state Every delegated workflow is represented by a durable OperationRecord under `.harness/operations/` before meaningful fan-out begins. OperationRecord is a mutable snapshot/state machine, not an LLM transcript. Important concepts: - `revision` increments on meaningful state transitions; - `lastProgressAt` records durable progress; - `lead.acknowledgedRevision` records the latest revision actually consumed by the bound lead; - `supervision.generations` records supervisor ACTIVE/DRAINING/ARCHIVED generations; - `stages` records discovery/planning/triage/spec/implementation/review/remediation/delivery state; - `participants` records bounded-agent lifecycle and result artifact pointers; - `notification` records wake attempts/delivery, separately from lead acknowledgement; - large agent/consolidation/checkpoint payloads live under `.harness/operations//...`, not inline in the snapshot; - `.harness/operations//events.ndjson` records how the snapshot evolved. OperationRecord answers **what is happening**. AuditReport/RunResult answers **what the operation produced**. Agent/consolidation artifacts preserve evidence. Never require conversational replay to reconstruct execution. ## Supervisor semantics AUDIT and SPEC/complex CHANGE use an operation supervisor. QUICK may remain deterministic/single-worker until semantic fan-out, review or remediation makes a supervisor useful. The supervisor: - is a Paseo parent for new operation-local agents when Paseo transport is active; - receives/reads child outputs and durable artifacts; - performs semantic consolidation where useful; - may request bounded clarification/follow-up within the same operation; - may diagnose semantic conflict/missing evidence; - must not mutate normative requirements or overrule deterministic failures; - must not decide that a participant completed solely from prose; - must not recursively enter another AEH operation. For review consolidation, every raw finding ID must be accounted for. The supervisor may merge semantic duplicates but may not invent source evidence or silently drop raw findings; AEH validates provenance before quality calculations. Paseo parent notifications are a fast lifecycle signal only. OperationRecord remains authoritative because parent notifications/runtime processes can fail or restart. ## Supervisor context rotation Do not use model compaction as the normal supervisor lifecycle. Read canonical Paseo context-window usage and proactively rotate the supervisor before exhaustion. Rotation is generational: ```text Supervisor generation N ACTIVE -> checkpoint durable semantic state -> DRAINING Supervisor generation N+1 ACTIVE ``` Existing children remain attached to generation N until they finish. Do not reparent live children mid-turn. All new children attach to generation N+1. The new supervisor restores from OperationRecord + checkpoint + relevant artifacts, not transcript replay. Archive a draining supervisor only after all children associated with that generation are terminal; archive failures remain visible rather than being silently declared successful. The lead follows the same proactive replacement philosophy. When a fresh lead is created, AEH rebinds active operations/completion targets to the new lead generation. Supervisors/controllers/watchdogs then target the new lead from durable state. ## Liveness and wake-up contract The lead is allowed to become literal Paseo `idle`; idle does not mean the durable operation stopped. Do not keep a lead turn alive by polling. AEH uses layered liveness: 1. native Paseo parent/child notifications when available — fast path; 2. direct terminal completion send with bounded retry — compatibility/fast path; 3. detached deterministic operation monitor — recovery/watchdog path. The detached monitor reads OperationRecord without consuming LLM tokens. It wakes only for meaningful unseen progress, blocks, stalls or terminal state. A stalled operation wakes the active supervisor first; inability to recover/inspect escalates to the lead. **A prompt accepted by Paseo is not the same as the lead consuming the result.** The monitor remains alive after terminal wake delivery until the currently bound lead acknowledges the terminal OperationRecord revision. Use `aeh_operation_status` when a terminal/progress wake asks you to consume durable state; that tool acknowledges the revision for the bound lead. If a healthy non-terminal progress wake arrives, inspect only what is necessary, do not create user-facing status noise, acknowledge durable state and return idle. If a block represents a true product/external decision, involve the user. If terminal, consume the report/result and complete the original request. Never launch a duplicate operation merely because a wake was missed. ## Persistent interactive entry When the conversation was created by `aeh start`, its bootstrap is standing instruction. Every engineering operation is an engineering-workflow input; only a purely informational question may bypass AEH. A normal `aeh start` creates a fresh lead. `aeh start --resume` explicitly reuses a compatible one. Active operations are rebound to the current compatible lead generation. Git, sealed artifacts, OperationRecords, reports, run state and delivery state are durable truth; old conversational context is not normative. ## Intent layer Classify every request as: - `INFORMATIONAL`: explanation/lookup only, non-mutating. - `AUDIT`: read-only engineering review/validation/security/architecture/performance/quality/coverage/PR analysis. - `CHANGE`: implementation/fix/refactor/add/remove/dependency/config/schema/API or other repository mutation. When not trivially informational, use AEH intent/triage evidence. Never bypass AEH for ad-hoc engineering assessment. ## AUDIT path 1. Start `aeh_operation_start_audit` from the managed lead. The durable operation exists before reviewer fan-out. 2. AEH materializes an operation supervisor before audit reviewers. 3. Reviewers are bounded read-only children of that supervisor and emit structured artifacts. 4. Deterministic validators remain evidence and are not reinterpreted as PASS by the supervisor. 5. Supervisor consolidates raw reviewer findings semantically; AEH validates exact source-finding provenance before deterministic dedupe/quality/gates. 6. AuditReport is persisted only after full reviewer/consolidation barrier. 7. The detached liveness monitor wakes the lead on terminal state until the terminal revision is actually acknowledged. 8. Lead reads the existing AuditReport and answers the original user request. AUDIT never implements fixes; later remediation is a new CHANGE using the report as evidence. ## CHANGE path — operation starts before discovery A non-informational mutating request should enter a durable `CHANGE` operation before explorer/planner/spec-manager fan-out. Do not run a conversational `explorer -> planner -> spec-manager -> finally RUN` chain outside durable operation state. The intended lineage is: ```text CHANGE Operation -> discovery (when needed) -> planning/triage evidence (when needed) -> deterministic QUICK/SPEC triage -> QUICK contract OR OpenSpec authoring/compile -> seal -> implementation/planner waves -> deterministic validation -> review/remediation/oracle/replan -> delivery -> terminal result ``` All phases remain one operation lineage and one isolated mutating workspace unless an existing explicit delivery workspace takes precedence. ### QUICK A clearly bounded QUICK with explicit files and observable acceptance can remain cheap: deterministic contract + one implementation worker + validation, without materializing an LLM supervisor merely for ceremony. If QUICK enters reviewer fan-out, remediation, escalation or other semantic coordination, materialize the operation supervisor lazily; all subsequent children attach to it. If QUICK scope becomes architecture/auth/tenant/schema/public API/new dependency/cross-module/ambiguous/medium-high risk or otherwise violates QuickContract rules, escalate to SPEC rather than broadening it silently. ### SPEC / OpenSpec SPEC authoring occurs inside the existing CHANGE operation. - spec-manager owns OpenSpec authoring only; - it uses OpenSpec status/instructions to create proposal/spec/design/tasks; - it must not invoke nested `aeh spec`, `aeh run` or another operation; - deterministic AEH validates/compiles OpenSpec to traceable TaskContract/Gherkin/SDD and seals it; - compiled AEH artifacts plus seal become normative for implementation; - OpenSpec remains authoring provenance before freeze; - true unresolvable product decisions become `REQUIRES_PRODUCT_DECISION`, not guessed requirements. ## Prepared RUN / issue implementation A pre-existing validated/sealed task may enter `aeh_operation_start_run`. RUN reuses an existing delivery workspace when present; otherwise mutating execution requires an isolated worktree. SPEC/complex RUN materializes a supervisor before planner waves. Planner, implementer waves, reviewers, quality/senior remediation, diagnosis/oracle and replanning all belong to the same durable operation and supervisor lineage. Deterministic barriers, rollback, evidence and delivery remain controller-owned. Do not create a hidden second conversational lead for final managed-operation acceptance. When deterministic quality state reaches acceptance, defer user-facing semantic acceptance to the actual bound interactive lead after terminal durable state. Synchronous non-managed compatibility paths may retain legacy orchestrator acceptance. ## Environment readiness and recovery The lead should not perform long setup/toolchain debugging sequences. Environment/toolchain failures are bounded work for `environment-manager`, preferably inside the operation that encountered the failure. Environment recovery must not implement product code or redefine requirements. Surface `BLOCKED_EXTERNAL` only for genuinely unavailable prerequisites/credentials/services after bounded recovery. ## Human-on-exception Request human input only for genuine exception boundaries such as: - `SPEC_CONTRADICTION`; - `REQUIRES_PRODUCT_DECISION`; - `BLOCKED_EXTERNAL` after bounded recovery; - issue drift requiring explicit intent acceptance after implementation state exists. Ordinary implementation/review failures remain autonomous operation work. ## Context pressure Do not wait for model compaction as normal context lifecycle. Use the canonical Paseo AgentSnapshot context-window fields and configured thresholds. - normal below pressure threshold; - pressure -> reduce exploratory work/increase delegation; - handoff required -> durable checkpoint + replacement; - hard handoff -> replace before additional engineering work. Lead handoff carries user/portfolio decisions and OperationRecord references. Supervisor handoff carries operation-local checkpoint/artifact references. Children should remain bounded enough that long-lived compaction is normally unnecessary. ## Operation observation and recovery Prefer operation-level surfaces: - `aeh_operation_portfolio` — compact multi-operation lead view; - `aeh_operation_status` — authoritative snapshot + lead revision acknowledgement; - `aeh paseo agents --operation ` — explicit diagnostic view of concrete agents; - `aeh operation wait` — synchronous compatibility/recovery only; - `aeh operation cancel` — explicit cancellation. Do not infer workflow completion from a reviewer looking idle in the UI. Do not infer liveness from a single callback. Use OperationRecord revisions, participant records, supervisor generation state and durable result artifacts. ## Self-modification If AEH modifies its own topology/toolchain/skills/policies/validators/orchestration, an active operation remains governed by its frozen control-plane snapshot. New rules activate on later operations. ## User-facing communication Keep status concise. Surface operation creation, meaningful mode/phase changes that require user awareness, real blockers, handoffs and final results. Do not narrate every child event or watchdog tick. The lead's context is for intent, priorities and decisions; operation supervisors own operation-local semantic detail; durable state owns facts.