mb-execute — Execution loop (plan → build → gates → verify → MB-SYNC)

• What it does: implements one scoped task and records the run in protocol files.
• Use it when: TASK-* already exists and you want a clean, resumable implementation flow.
• Input: TASK_ID plus links to the driving feature, requirement, and backlog entry.
• Output: code changes, protocol artifacts, verification inputs, and synchronized Memory Bank state.

Goal

Turn a backlog item into a reproducible, verifiable change:

• clear plan
• bounded implementation
• deterministic gates
• recorded verification
• synchronized Memory Bank

Inputs

Orchestrator must provide:

• TASK_ID (e.g. TASK-123)
• link to the driving spec(s):
  • .memory-bank/features/FT-*/... and/or
  • .memory-bank/requirements.md (REQ IDs)
  • .memory-bank/tasks/backlog.md entry

Required artifacts

Create:

• .protocols/<TASK_ID>/context.md
• .protocols/<TASK_ID>/plan.md
• .protocols/<TASK_ID>/progress.md
• .protocols/<TASK_ID>/verification.md
• .protocols/<TASK_ID>/handoff.md

And a runtime folder:

• .tasks/<TASK_ID>/

Use templates from:

• ./references/shared-protocols-context-template.md
• ./references/shared-protocols-plan-template.md
• ./references/shared-protocols-progress-template.md
• ./references/shared-protocols-verification-template.md
• ./references/shared-protocols-handoff-template.md

Process

1) Prime context (cheap-to-prime)

Read only what you need:

• AGENTS.md
• .memory-bank/index.md
• the specific FT-* / REQ-* relevant to TASK_ID

2) Write the plan (before touching code)

In .protocols/<TASK_ID>/plan.md:

• goal + non-goals
• touched files/modules (hypotheses allowed, mark as such)
• constraints/invariants
• quality gates to run
• MB-SYNC step is mandatory (link to .memory-bank/workflows/mb-sync.md)

3) Implementation (fan-out allowed)

If work is non-trivial:

• spawn subagents (max depth=2)
• give each worker a narrow scope (≤3–5 files)
• workers write details to .tasks/<TASK_ID>/...

Recommended role split (optional):

• Implementer: changes code/tests — ./agents/shared-implementer.md
• Secretary: keeps progress.md updated — ./agents/shared-secretary.md

3.1) Fresh Codex session per task (optional, clean context)

If you want the implementation to run in a fresh Codex session (clean context), run it via shell:

codex exec --ephemeral --full-auto -m gpt-5.2-high \
  'TASK_ID=TASK-123. Read AGENTS.md, .protocols/TASK-123/context.md, .protocols/TASK-123/plan.md, .protocols/TASK-123/progress.md. Keep context.md updated. Implement only scoped changes. Write report to .tasks/TASK-123/TASK-123-S-IMPL-final-report-code-01.md. Update .protocols/TASK-123/progress.md.'

Then run verification in another fresh session:

codex exec --ephemeral --full-auto -m gpt-5.2-high \
  'TASK_ID=TASK-123. Read .protocols/TASK-123/context.md, .protocols/TASK-123/plan.md and progress.md + acceptance criteria. Keep context.md updated. Fill .protocols/TASK-123/verification.md and put evidence in .tasks/TASK-123/. VERDICT: PASS/FAIL.'

3.2) Fresh Claude session per task (required when working in Claude Code)

If you are running inside Claude Code, enforce clean context by executing each TASK-XXX in a fresh Claude session:

Run implementer in a fresh session via shell (new session, clean context):

claude -p --no-session-persistence --permission-mode acceptEdits --model opus \
  'TASK_ID=TASK-123. Read AGENTS.md, .protocols/TASK-123/context.md, .protocols/TASK-123/plan.md, .protocols/TASK-123/progress.md, and acceptance criteria docs. Keep context.md updated. Implement only scoped changes. Update .protocols/TASK-123/progress.md. Write report to .tasks/TASK-123/TASK-123-S-IMPL-final-report-code-01.md.'

Then run verifier in another fresh session:

claude -p --no-session-persistence --permission-mode acceptEdits --model opus \
  'TASK_ID=TASK-123. Read .protocols/TASK-123/context.md, .protocols/TASK-123/plan.md + progress.md + acceptance criteria docs. Keep context.md updated. Fill .protocols/TASK-123/verification.md and store evidence in .tasks/TASK-123/. VERDICT: PASS/FAIL/NEEDS-CLARIFICATION.'

3.3) Sequencing rule (dependencies)

• If tasks are independent (no dependency and no shared files), you MAY run them in separate clean sessions in parallel.
• If tasks have a dependency chain (TASK-B requires outputs from TASK-A), run them sequentially, one after another, each in its own clean session.
• If tasks touch the same files, treat them as dependent unless you isolate via worktrees/branches.

4) Quality gates (deterministic)

Run the repo’s canonical gates (from AGENTS.md). Minimum:

• lint / typecheck
• unit tests
• integration/e2e when relevant

If any gate is flaky, record it in progress.md and (if needed) file a bug doc in .memory-bank/bugs/.

5) Verification handoff

Do not self-validate beyond sanity checks.

• Hand off to mb-verify (fresh-ish context) to fill verification.md.

6) MB-SYNC (required, last step)

After verification is complete:

• update .memory-bank/ docs (only WHY/WHERE + navigation)
• update .memory-bank/index.md routers if needed
• update .memory-bank/requirements.md RTM status (if used)
• mark the backlog task with the correct state (done / failed / blocked)
• append a record to .memory-bank/changelog.md

Definition of done

• Protocol folder exists with all 5 required files.
• Gates pass (or failures are explicitly recorded + bug filed).
• verification.md contains evidence links to .tasks/<TASK_ID>/.
• Memory Bank is synced + changelog updated.