plumbline-execute-engine

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Execute engine

## Outcome and completion

Execute the approved work through every remaining checkpoint in dependency
order. A checkpoint boundary is an internal team handoff, not a user-prompt
stop. Normal Execute is full-plan mode; checkpoint-by-checkpoint mode exists
only when the user explicitly requests one checkpoint, a named pause, or
approval at each boundary.

Execute is complete only when every required checkpoint is `Complete`, the
stable delta has focused/full proof, the plan says `Ready for Acceptance`, and
the main thread has reported the remaining risk. The main thread assesses
`CHANGES_REQUIRED` and `INCONCLUSIVE` reports under `references/qa-audit.md`;
confirmed acceptance blockers, `Blocked`/`Reopened` checkpoints, and missing
required proof remain unresolved work and never satisfy completion. Execute may
clean clearly task-owned superseded diagnostic/build scratch as it works. Accepted-work
Closeout owns specification/plan retirement, integration cleanup, and publishing.

Resolve `execution_mode` before traversal. A missing value means `continuous`.
**Checkpoint Relay:** when the plan explicitly sets `checkpoint_relay`, load
`references/checkpoint-relay.md` immediately and follow its complete branch for
adoption/readiness, controller versus checkpoint-task behavior, durability,
recovery, and acceptance. Continuous mode follows the execution loop below.

## Resume from the smallest sufficient evidence

At task start or resume, read the controlling plan's compact resume record,
external work order, or supplied execution artifact first. Use checkout/
worktree identity, HEAD or `last_verified_commit`, the artifact/plan-record
hash, and relevant local agent hashes as the resume fingerprint.

When the fingerprint is unchanged, read the compact record, Git delta, and next
action. At each checkpoint, read the exact checkpoint, its referenced contract
sections, changed files, relevant canonical documentation, and validation
commands. Read larger source/spec sections only when a referenced section or a
material trigger requires them. Resolve the Plumbline installation root once
at phase entry and use that root for all reference paths.

Reuse prior completion evidence when referenced inputs and the fingerprint are
unchanged. Reassess after a relevant source, specification, or plan change; a
config or agent change that materially affects capability or permission; a
failed or newly relevant check; a contract-boundary change; a defect; or stale-
evidence concern. A new session, compaction, or conversational resume alone
does not invalidate evidence.

A changed project-local role or config hash is a profile refresh, not role loss
or automatic evidence invalidation. Reread the current files, update the
compact fingerprint, and use their current values for new dispatches; workers
already running retain the profile used at creation. If a selected role is
missing in the active worktree, perform the bounded on-demand refresh described
in `references/worktree-readiness.md` before using `Direct: <reason>`.
Workers already running retain their creation profile; only new dispatches use
the refreshed values.

## Use Git as the recovery boundary

When the checkout is Git-controlled, material multi-checkpoint execution uses a
required Git policy by default. Create main-thread commits at coherent
checkpoint or batch boundaries unless the user explicitly opts out; state the
policy once without blocking for approval. Capture the starting `HEAD`,
separate unrelated dirty work, scratch, and secrets, and establish a clean
plan-owned boundary before the first checkpoint. After each accepted
checkpoint, commit its intended tracked changes, record the commit in the
compact plan state, and begin the next checkpoint from that clean boundary. Do
not advance dependent work while plan-owned changes remain uncommitted. Ask
before push, force-push, history rewriting, or external publication. Workers
never commit.

If no Git repository exists, recommend `git init` before material Execute work.
An explicit user opt-out permits continuation but must be reported as
Git-unanchored. Never stage unrelated changes, ignored agent setup, secrets,
build output, or diagnostic scratch. Use the checkpoint commit with `git show`
or a focused `git diff` as the first worker hydration context.

## Conditional artifact sufficiency preflight

Accept a user-supplied or repository-local specification, plan, work order, or
execution artifact when it defines enough scope, topology, proof, and next
action. A sufficient specification without a separate plan may receive a
companion plan recommendation, but execution can continue when the artifact
already defines the safe slice and acceptance. Missing Plumbline paths,
frontmatter, or checkpoint IDs are not blockers by themselves.

Report only adoption, a companion recommendation, competing candidates, or a
real blocker. Recommend Plan or Shape when the artifact lacks an executable
boundary or a material product decision remains unresolved.

## Traverse the full plan

This section applies to `continuous` mode. Relay traversal uses the same
checkpoint loop and evidence rules for one current checkpoint, then applies the
Relay boundary above.

After bounded work, review, focused proof, and main-thread integration complete
one checkpoint, update its resume record, select the next safe checkpoint, and
continue without waiting for a user prompt. Do not report `Ready for
Acceptance` between checkpoints. Continue independent safe checkpoints when
the topology permits, while a blocked or reopened checkpoint waits for its
resolution. A failed checkpoint attempt returns to Diagnose, then correction
of the same active candidate and checkpoint, followed by review. Do not revert
a candidate, close the objective, or select a successor merely because a
review found a defect or evidence is inconclusive.

Once an approved specification and plan are active, they are product-scope
authority for execution, but they cannot override Plumbline lifecycle
invariants. The main orchestrator resolves ordinary in-scope
ambiguity from the approved outcome, repository evidence, and a safe reversible
default, then records the decision, assumption, or residual risk. A worker's
`Shape question` label is an internal escalation; it does not itself invoke
Shape, end the goal, or pause for the user. Reopen Shape or stop only for an
explicit user gate, a destructive action outside approved authority, or a
contradiction with no safe in-scope default. When no safe default exists, block
only the affected checkpoint and continue independent work.

## Forward progress and delegation

Keep the orchestrator thin. Read the compact plan/work order, repository
guidance, current Git state, and explicitly named paths needed to route the

From nickyfactz/plumbline, MIT.

More from nickyfactz/plumbline