Evidence first durable task orchestrator

Evidence-First Durable Task Orchestrator

For a genuinely complex task, make the Agent design before it implements. The Design Gate requires a reviewable objective, boundaries, assumptions, material decisions, risks, and acceptance criteria before broad changes may begin. Markdown records preserve that approved thinking for execution, recovery, and verification; they are a means, not the primary goal.

Design Gate first. Execution second. Evidence always.

1. Entry gate — decide before loading this workflow

Use this workflow when one hard condition or two soft conditions are true.

Hard conditions:

• the user explicitly asks for durable task tracking or cross-session recovery;
• production change, release, public compatibility, migration, bulk deletion, authentication, authorization, payment, security, irreversible action, or meaningful cost;
• a project policy explicitly requires this workflow.

Soft conditions:

• two or more dependent subsystems;
• several dependent delivery stages;
• more than one independent form of acceptance evidence;
• a material ambiguity affecting architecture, data, cost, public behavior, or a main flow;
• recovery, handoff, or reconciliation will be needed after a failure.

Do not use this workflow merely because the task has many files, many steps, tests, research, or an ordinary cross-module change. Use the host agent's normal planning instead.

2. Design Gate — no broad implementation before this passes

Before modifying implementation files, the Agent must:

1. understand the current project instructions and live baseline;
2. define the objective, deliverables, non-goals, constraints, and success conditions;
3. identify facts, assumptions, material ambiguities, risks, and rollback boundaries;
4. resolve or obtain confirmation for decisions that change architecture, data, cost, public behavior, permissions, privacy, or irreversible outcomes;
5. define dependency-ordered milestones and observable acceptance criteria.

The gate passes only when the requirement contract is complete, blocking ambiguity is resolved, scope boundaries are clear, risks are recorded, and every required criterion has a verification method. Until then, investigate or ask focused questions; do not start broad implementation.

The task record stores the gate decision and evidence. It is not a substitute for the gate.

3. Choose storage and mode

Read configuration. Look for <project-root>/.evidence-first-task.yaml; if it is absent, use <project-root>/.agent-tasks/. Create plain Markdown records from assets/task-template.md.

When the user asks to initialize or integrate this workflow, use the separate evidence-first-workspace-setup Skill. It creates the optional configuration and a safe AGENTS.md suggestion without overwriting project instructions.

• autonomous-safe: default for reversible, low-risk decisions.
• alignment-first: wait for the user before material architecture, data, cost, public, permission, privacy, or irreversible decisions.
• plan-only: investigate and prepare a record without changing implementation files.

The optional obsidian-task-board Skill can display the same Markdown records in Obsidian. It is not required to create, read, or update them.

4. Preflight

Before modifying the target project:

1. Read applicable project instructions and authoritative project documents.
2. Record the project root, current Git status when available, and pre-existing changes.
3. Search the task directory for matching Active or Blocked work. Resume only after reconciling record, files, tests, and external state.
4. Search related archived records. Treat them as historical evidence, never current truth; revalidate anything that may have changed.
5. Verify that the task directory is writable. If it is not, state that fact and use a user-approved fallback directory. Never pretend an update was persisted.

5. Requirement contract and readiness

Create or update the task record before broad implementation. Record:

• objective, deliverables, non-goals, constraints, success conditions;
• supported facts, assumptions, material ambiguities, risks, and scope boundaries;
• a dependency-ordered milestone list;
• acceptance criteria written before implementation.

Each required acceptance criterion must identify an observable target, trigger, expected result, verification method, evidence location, and a final PASS, FAIL, or NOT VERIFIED verdict. See acceptance criteria.

Do not start implementation until blocking ambiguities are resolved, allowed paths are clear, and every required criterion has a verification method.

6. Execute one milestone at a time

For every milestone:

1. Record the current baseline and mark only that milestone in progress.
2. Make changes only within its allowed scope. Log material decisions and assumptions.
3. Run each planned verification and attach command, result, expected result, actual result, and evidence path to the record.
4. If a required check fails, preserve the failure, revise the hypothesis, and rerun affected checks after a materially different fix. Do not advance while a required check is failing.
5. Mark the milestone passed only when all of its required criteria are PASS.

7. Independent review and closure

Use a separate, adversarial review pass for public interfaces, releases, security, migrations, or other high-impact work. Review against the original contract and evidence, not the implementer's self-assessment.

Before closing:

1. Confirm deliverables exist and inspect the final diff or file state.
2. Run the required final regression checks.
3. Record unresolved items and residual risks.
4. Write only evidence-backed reusable lessons and a short list of facts that must be revalidated by a future related task.
5. Archive completed records; leave partial or externally blocked records active/blocked.

Safety boundaries

• A task board is coordination metadata, not a file lock. Check live Git/filesystem state.
• Never lower acceptance criteria after seeing an implementation result.
• Never claim verification was run when it was not.
• Do not read, copy, or publish credentials, tokens, cookies, private paths, or task content.
• Do not create a remote repository, push, publish, release, deploy, or change external state without the user's explicit approval.

References

• Configuration and storage
• Task classification and modes
• Acceptance criteria
• Record lifecycle
• Task record template