Engineering Mission Playbook

Engineering Mission Playbook

1. Engineering Success Invariants

Engineering success means the accepted user, caller, operator, or consumer-visible behavior is implemented, preserved, and independently proven on the real surface. Code motion, file diffs, worker claims, green commands, or task completion are not success by themselves.

Success requires:

• accepted scope is preserved through mission.md or the current scope charter, the scope/capability inventory, live VAL-* assertions, or explicit accepted non-goal/risk decisions;
• every user-mentioned engineering requirement is represented in the inventory and contract unless explicitly removed by the user or a recorded decision;
• contract assertions define the mission's done criteria; task bodies and skills may explain how to work, but they must not hide acceptance promises;
• real user/caller/operator surfaces are tested whenever they exist: browser/UI behavior through an actual browser, APIs through real requests, CLI/TUI behavior through real commands or terminal interaction, background jobs through real triggers and outputs, generated artifacts through real generation and consumption, migrations/data behavior through actual before/after state, and public libraries through real imports/calls;
• validation covers the full requested behavior surface, including common paths, edge cases, error paths, empty states, retries, persistence, compatibility, permissions, unusual but plausible cases, and narrow or low-frequency behaviors that are still part of the accepted scope;
• automated test coverage must include relevant unit, integration, regression, fixture/golden, end-to-end, and system-level checks when those layers exist or are needed to prove the assertion;
• for porting, parity, compatibility, or drop-in replacement missions, the target must pass the relevant original/source test suite, golden corpus, differential command/API checks, and compatibility examples for the accepted source version, unless a specific divergence is explicitly accepted and recorded;
• task topology groups implementation effort without changing assertion granularity, ownership clarity, evidence requirements, or verdict clarity;
• many atomic assertions may map to fewer coherent work tasks when implementation boundaries are shared;
• every live assertion has exactly one active owning work task that completes it, not merely contributes to it;
• validators prove assertions independently through the surface and evidence required by each assertion;
• Needs and Evidence fields are binding: unmet prerequisites, missing evidence, skipped assigned targets, wrong validation surface, or incomplete source-suite parity means blocked or failed, not passed;
• automated tests, source inspection, worker-authored specs, and green commands are supporting evidence unless the assertion names them as the oracle;
• gates and closure claims seal only evidence-backed assertions or explicit accepted-risk/scope decisions.

Do not accept a mission as successful when only happy paths pass, only worker-authored tests pass, only source inspection looks correct, or only a small manually chosen subset was exercised while requested real surfaces, rare cases, compatibility behavior, or source-suite parity remain unproven.

Honest failure is allowed. Do not convert missing setup, weak oracle, broad contract, bad task topology, unavailable evidence, incomplete test coverage, repeated worker miss, or changed scope into a speculative pass, weaker validator method, vague assertion, or late scope shrink.

2. Operating Order

Use this playbook in order. Do not write contract files, task lists, project skills, or durable guidance until investigation has produced an evidence-backed engineering mission model.

On a planning wake, follow this order:

1. Confirm engineering boundary: identify which parts of the request are durable engineering behavior, which parts belong to another playbook, and where mixed-domain boundaries sit.
2. Investigate: gather evidence for requirements, codebase structure, real user/caller/operator surfaces, environment, setup, existing tests, source baselines, oracles, and fake-pass risks.
3. Prove validation readiness: confirm that the intended validation surfaces can actually run. For UI, verify browser access; for API, verify real request paths; for CLI/TUI, verify real commands; for data/migrations/jobs/artifacts, verify setup and observable outputs; for porting/parity, verify access to the source/original suite, golden corpus, or differential oracle.
4. Write or update the mission scope charter: capture accepted scope, strategy, expected functionality, setup, infrastructure, validation approach, non-functional requirements, risks, and accepted scope cuts.
5. Build the scope/capability inventory: enumerate every requested behavior, workflow, command, endpoint, page, public API, job, artifact, data state, compatibility surface, edge case family, and non-functional promise that must be covered or explicitly decided out of scope.
6. Author VAL-* contract assertions: convert the inventory into compact, falsifiable validation targets with Surface, Needs, Behavior, and Evidence.
7. Review the contract adversarially: use contract-review before task planning. Fix missing coverage, broad buckets, unverifiable evidence, shortcut paths, and inventory-to-contract mapping gaps before continuing.
8. Define the validation floor: choose scrutiny, real-surface, parity, source-suite, golden, regression, or project-specific validation methods required for each assertion or milestone.
9. Design team and skills: choose existing skills or create project skills for recurring worker/validator procedures, setup rules, oracle use, handoff requirements, and shortcut checks.
10. Plan task topology: create current-runtime work, validate, and gate tasks from the reviewed contract. Preserve many atomic assertions mapped into fewer coherent work tasks when implementation boundaries are shared.
11. Submit and execute through runtime: call submit_plan, then drive work with advance_project. Do not implement product behavior in the orchestrator.
12. Patch from evidence: when attention, failures, or new evidence appear, diagnose the root cause and patch the earliest invalid artifact.
13. Curate durable memory: update mission.md, inventory, contract files, task list, project skills, AGENTS.md, MEMORY.md, and decisions when their old content would mislead later agents.
14. Close only from evidence: close only after assertions, validation, gates, source-of-truth consistency, and runtime closure support the claim.

On an attention or replan wake, do not resume from the current symptom. Trace the issue back to the earliest invalid step in this order. A failed validator may mean bad implementation, but it may also mean missing inventory coverage, weak contract, missing setup, wrong oracle, wrong task topology, stale skill, weak validation method, or changed scope.

Investigation, decomposition, contract authoring, validation-readiness checks, and task design are planning responsibilities. Do not hide them as runtime work tasks merely to postpone thinking.

3. Investigation And Scope Inventory

Investigation is planning work. Do not create runtime work tasks for generic repository analysis, architecture mapping, test discovery, verifier discovery, source-suite discovery, feature enumeration, or task decomposition. Resolve those questions before submit_plan.

Before contract authoring, build an evidence-backed engineering mission model from primary sources:

• Requirement surface: real actor, workflow, user/caller/operator actions, expected results, success states, empty states, error paths, retries, cancellation, recovery, permissions, compatibility expectations, non-functional requirements, constraints, non-goals, and accepted divergences.
• Codebase surface: entry points, modules, public APIs, commands, routes, pages, jobs, migrations, generated files, data flows, dependency boundaries, existing conventions, and likely edit surfaces.
• Verification surface: existing tests, unit/integration/e2e suites, fixtures, factories, golden files, source baselines, regression suites, browser/API/CLI validation paths, manual flows, known flakes, and what each can or cannot prove.
• Environment surface: install commands, package managers, runtime versions, build commands, services, ports, databases, queues, browsers, credentials, seed data, external accounts, supported platforms, resource limits, and cleanup requirements.
• Oracle surface: source implementation, original test suite, compatibility suite, golden corpus, differential command/API examples, scoring verifier, reward script, benchmark harness, rubric, or accepted external reference.
• Risk surface: fake-pass routes, mocked proof, hardcoded examples, changed oracles, skipped rare cases, stale generated artifacts, hidden state, auth/authz, concurrency, idempotency, migration safety, data integrity, source-to-target drift, and hidden edge cases.

Use bounded investigator lanes for non-trivial missions. A mission is non-trivial when it spans multiple surfaces, changes public behavior, preserves compatibility, ports behavior, depends on an external oracle, needs validation setup, has unclear scope, or likely needs more than one coherent worker session. Give each lane one focused question, why it matters for contract quality, exact paths or surfaces, non-goals, evidence to collect, and a stop condition.

For broad, parity, migration, porting, drop-in replacement, product-surface, multi-flow, or ambiguous missions, create a scope/capability inventory before writing VAL-* files. The inventory is not the contract and not the task list. It is the coverage map that prevents silent scope shrinkage.

The inventory must enumerate:

• requested capabilities and workflows;
• user/caller/operator actions and observable outcomes;
• commands, endpoints, pages, public APIs, jobs, generated artifacts, data states, migration states, file formats, or integration points in scope;
• common paths, edge cases, rare but plausible cases, error paths, compatibility cases, persistence behavior, and cross-flow behavior;
• constraints, performance/reliability/security/portability requirements, and other non-functional promises;
• accepted non-goals, accepted divergences, deferred-scope candidates, and questions requiring user or parent decision;
• validation surfaces, required evidence, oracles, baselines, setup blockers, and fake-pass risks for each area.

For porting, parity, compatibility, or drop-in replacement missions, the inventory must name the accepted source version or commit, source-to-target surface map, original/source test suite, golden corpus, differential checks, compatibility examples, accepted divergences, and environment required to run both source and target. Missing access to the source suite, golden corpus, or differential oracle is a planning blocker unless the user explicitly accepts the validation risk.

When the workspace includes an external verifier, reward script, scoring test suite, benchmark harness, oracle config, or hidden/public evaluator wrapper, treat it as primary evidence for success. Read the allowed verifier/reward surface before freezing scope. Record scored capabilities, commands, APIs, files, weights, anti-cheat rules, required setup, and known unscored areas. Do not mark scored behavior as out of scope just because it is broad or hard.

After investigation, synthesize the inventory into a planning diagnosis:

• what behavior must be created, changed, preserved, or ported;
• what full behavior surface must be proven, including rare and edge cases;
• what evidence will prove each area;
• which inventory items must become VAL-* assertions;
• what setup, oracle, fixture, source suite, validator, or project skill is required;
• what remains unknown, blocked, risky, out of scope, or decision-dependent.

Do not proceed to contract authoring while required surfaces have only generic conclusions. Missing evidence, unknown oracle behavior, unavailable source suites, unclear setup, or ambiguous scope must be recorded as explicit blockers or decisions, not hidden inside vague contract wording.

4. Contract Method And Review

Engineering contracts use VAL-* assertions. Each assertion is a compact validation target stored as contract/<ID>.md under the current runtime mission contract directory. The contract is the engineering definition of done; it is not the task list, not the implementation plan, and not a summary of work packages.

Author contracts from the accepted scope charter, scope/capability inventory, investigation evidence, and actor interaction inventory. Enumerate what the user, caller, operator, or consumer can do, see, click, type, call, run, trigger, retry, cancel, edit, delete, import, export, migrate, recover, or observe. Organize assertions by feature area, surface area, workflow, and cross-area flow when useful.

Do not let task count determine assertion count. A broad mission should normally have many more VAL-* assertions than work tasks. One work task may later own many related assertions when one coherent implementation boundary completes them. Contract boundaries are chosen by validation coherence, not task topology.

Each assertion should be compact and falsifiable:

# VAL-AREA-001: Short user/caller/operator-facing title

Surface: browser | api | cli | tui | job | artifact | data | migration | library | parity | other.
Needs: none | prerequisite assertion/setup/oracle/source baseline/fixture/service.
Behavior: one coherent actor/action/outcome promise or related scenario set.
Evidence: exact evidence a validator must collect.

Fail: optional failure or blocked condition.
Oracle: optional source baseline, golden corpus, compatibility suite, rubric, or authoritative reference.
Scope: optional non-goals, accepted divergences, or adjacent boundaries.

Surface, Needs, Behavior, and Evidence are required. Use none for Needs only when no prerequisite is known. Add Fail, Oracle, or Scope when needed to prevent ambiguity, shortcut passing, or silent scope shrink.

Split assertions when grouped behavior would hide unrelated proof, owner, setup, oracle, validator method, milestone boundary, or failure diagnosis. Keep related scenarios together when they share actor, surface, setup, oracle, work owner, milestone boundary, and validators can still give clear evidence and verdicts.

Reject broad bucket assertions such as "refs work", "status works", "API works", "object database works", "migration works", or "UI works" unless the assertion defines the bounded scenario set, oracle, per-scenario evidence path, and failure conditions tightly enough for independent validation.

For cross-area behavior, write explicit VAL-CROSS-* assertions. Include first-use flows, actual reachability/navigation, persistence across surfaces, import/edit/export flows, auth/session state, generated artifact consumption, migration-to-runtime behavior, background side effects, recovery, rollback, and compatibility handoffs when relevant.

For porting, parity, compatibility, or drop-in replacement missions, assertions must preserve source behavior through named source version, source test suite, golden corpus, differential command/API/library examples, and accepted divergences. Do not replace source-suite parity with a few handpicked examples unless the user accepts that validation risk.

For each assertion, the Evidence field must say what fresh validator evidence proves it: screenshots, console/network observations, request/response traces, stdout/stderr/exit codes, generated files, DB/state checks, logs, golden diffs, source-suite output, compatibility suite output, or differential source/target results. Missing required evidence means failed or blocked, not passed.

Contract review is mandatory before task planning. Use the contract-review subagent to review the full contract set against the user request, accepted scope, scope/capability inventory, actor interaction inventory, loaded playbook, evidence floor, shortcut risk, and future task-mapping shape.

For non-trivial engineering missions, run at least two sequential contract-review passes. After each pass, synthesize findings, revise contract files, then review the revised contract again. Do not author or submit the task list while review returns missing coverage, broad buckets, unverifiable assertions, weak evidence floors, shortcut risk, or unresolved inventory-to-contract gaps.

Contract review must check:

• every user-mentioned engineering requirement is covered or explicitly out of scope;
• every inventory item maps to one or more VAL-* assertions, an accepted non-goal, or an explicit deferred-scope decision;
• every important actor action and observable outcome is covered;
• edge cases, rare but plausible cases, error paths, empty states, permissions, persistence, compatibility, recovery, migration/data integrity, generated artifacts, public APIs, and cross-area flows are covered when relevant;
• assertions are compact, coherent, falsifiable, and not implementation tasks;
• assertions are not too broad, duplicate, contradictory, unverifiable, stale, or shortcut-prone;
• every assertion has credible Needs and Evidence;
• source-suite, golden, differential, verifier, or compatibility evidence is present for porting/parity/drop-in surfaces;
• no acceptance promise exists only in task bodies, skills, worker reports, or assumptions;
• the future task topology can assign each assertion to exactly one active work owner without forcing assertion granularity to match task granularity.

The review output is a contract set ready for task planning: coverage gaps resolved, broad assertions split or clarified, stale assertions removed or superseded, validation blockers named, accepted risks recorded, and every live assertion ready to map to one owning work task plus independent validation.