Call health_check first, loading it and boulder_write if needed: ToolSearch({query: "select:mcp__plugin_oh-my-claudeagent_omca__health_check,mcp__plugin_oh-my-claudeagent_omca__boulder_write", max_results: 2}). Proceed only when runtime is ok; otherwise repeat runtime_reason to the user, tell them to run /oh-my-claudeagent:omca-setup, and stop. If the tool is still missing, say OMCA's server is not connected and stop.

Plan execution mode: start-work

This command runs in the main session at depth 0. The Agent tool is available, so orchestration is real: parallel fan-out to executor, specialist escalation via build-fixer/explorer/researcher as needed.

The platform's native Workflow tool is not a substitute for this command. A workflow run is driven by the platform's own runtime, so its agents never call evidence_log, never bind a plan, and OMCA's plan gates never see them. That makes it a separate lane, not a replacement for plan execution here.

Refusal clause

This command body runs in the main session at depth 0. If the Agent tool is not in your tool list (a --tools, --disallowedTools, or deny-rule restriction removed it), refuse and return.

There is no degraded mode. Do not implement tasks directly. Do not attempt a partial execution. Emit the refusal message below and return:

ERROR: start-work needs the `Agent` tool to delegate plan tasks, and this session
does not have it. There is no degraded-mode fallback.

Run plan execution from a session where the Agent tool is available:
  /oh-my-claudeagent:start-work <plan>

Plan discovery logic (step 0)

Plan mode handling

When plan mode is active, call ExitPlanMode first. Plugin agents cannot set their own permissionMode, so delegated agents inherit plan mode and could not edit.

Finding the active plan

OMCA tracks several plans at once, and each session is bound to at most one of them. Plan selection in this step is what binds this session.

1. When the guidance OMCA added to this session carries an [ACTIVE PLAN] <name>: <path> line, this session is bound to that plan. If the file has an open - [ ] task, resume it directly (skip steps 2-3); boulder_progress(plan_name="<name>") gives the counts.

2. Otherwise, or when that plan has no open task left, build the selection list from two sources:

   • The plan boulder_progress() returns, labeled [active]. With no binding it returns the only registered plan or the most recently started one, which may be another session's. Exclude it when its checkboxes are all checked: completion is derived from the plan file's - [x] boxes, not a stored flag.
   • Plan files in <plans-dir>/*.md and <project root>/.omca/plans/*.md, labeled [available].

   <plans-dir> is the platform's plans directory: the plansDirectory setting when it is set (a path relative to the project root), otherwise ~/.claude/plans. Read it from settings before globbing; with plansDirectory configured, the default path holds nothing and a ~/.claude/plans glob finds no platform-created plan.

3. Merge results, deduplicate by absolute path. When the plan being registered sits outside both homes, tell the user its path and that the Plan tab lists the two homes and registered plans.

Decision logic

Draft gate (checked before anything is executed)

A plan may carry a **Status**: field on its metadata line. Read it before executing, resuming, or auto-selecting a plan:

• Status says FINAL: executable.
• No Status field anywhere in the plan: executable. A missing field never blocks execution.
• Status is present but says anything other than FINAL (DRAFT being the common case): REFUSE to execute it. A draft is a plan the user is still being interviewed about, and executing one runs work nobody agreed to.

On a refusal, emit this and return without delegating anything:

This plan is still a draft (Status: {value}), so start-work will not execute it.

Finish the plan first:
  /oh-my-claudeagent:plan

Once the plan's Status line reads FINAL, re-run:
  /oh-my-claudeagent:start-work {plan path}

A refused plan is also excluded from the selection list, so a single draft never auto-selects. If every candidate is a draft, say so rather than picking one.

• This session already resolves to a bound plan with an open task: append the session (re-run boulder_write, which is idempotent) and continue work.
• No bound plan, or the bound plan has no open task: list available plans (per above, completed plans excluded).
  • One plan found: auto-select it.
  • Several plans: present the list and ask the user to choose. Selecting a plan calls boulder_write, which registers the plan and binds this session to it.
• The selected plan has no open task, only - [~] tasks left: flip back to - [ ] each task whose gap is now resolved, and continue. If none is, report the plan as closed with its blocked tasks and stop.

Argument handling

If [plan file] argument is provided, use that path directly, skip search.

If --worktree <path> is provided:

1. Validate: git rev-parse --show-toplevel inside path.
2. If valid, store it in boulder via boulder_write and inject worktree instructions into ALL delegation prompts (all ops target worktree paths).
3. If invalid, show setup: git worktree add <path> <branch>.

Without --worktree, run in the current checkout; boulder_write keeps a worktree_path stored earlier for the plan.

Boulder write (before delegating)

After the plan is selected, before any delegation:

boulder_write(
  active_plan="<absolute path to plan file>",
  plan_name="<plan name>",
  session_id="<current session id>"
)

<current session id> is the platform session UUID (the Session <id> line OMCA adds to the session's first prompt, same as the transcript filename), not a locally-generated banner id. Passing the wrong id here is what desyncs the statusline TODO counter and every other session-id-keyed lookup against it.

boulder_write enforces deduplication and preserves started_at. The plan body stays at its authoritative location; boulder stores a pointer only.

Output formats

When listing plans for selection:

Available Work Plans

1. [plan-name-1.md] - Modified: {date} - Progress: 3/10 tasks
2. [plan-name-2.md] - Modified: {date} - Progress: 0/5 tasks

Which plan would you like to work on? (Enter number or plan name)

When resuming existing work:

Resuming Work Session

Active Plan: {plan-name}
Progress: {completed}/{total} tasks

Reading plan and continuing from last incomplete task...

When auto-selecting single plan:

Starting Work Session

Plan: {plan-name}

Reading plan and beginning execution...

Step 1: register and analyze

1. boulder_write(active_plan="<path>", plan_name="<name>", session_id="<current>"), before delegating.
2. Read the full plan file.
3. Parse - [ ] checkboxes.
4. Take the parallel groups from the plan: its **Parallel Execution** metadata and the [P] marker on parallel-safe tasks. Run two tasks together only when their File: paths do not overlap and every task in their Depends: is checked; in a plan without [P] markers, apply the same two tests to decide.

Delegation prompt

Every delegation prompt carries these five sections.

## 1. TASK
[Quote the task's checkbox line AND every sub-bullet beneath it, VERBATIM.
The checkbox line alone is a title, not a task.]

## 2. DONE WHEN
- [ ] Paths touched: [from the task's `File:` sub-bullet]
- [ ] Behavior: [what the code does afterwards]
- [ ] Proof: `[command]` passes, taken from the task's `Done when:` sub-bullet

## 3. TOOLS
- [tool]: [what it is for here]

## 4. SCOPE
- [Every requirement the task states: the pattern to follow at reference file:lines,
  the cases to test]
- [Every `Must NOT:` sub-bullet on the task, restated verbatim]
- Write the smallest diff that satisfies the task. Validation at trust boundaries, error
  and data-loss handling, security, and anything the task asks for are never what gets cut.

## 5. CONTEXT
### Dependencies
[What previous tasks built, resolved from the task's `Depends:` sub-bullet]
### Files in play
[The task's `File:` paths, plus what already exists at each]

§1: quote the whole task block, not just the checkbox line

Plan task labels are capped at roughly 80 characters because the statusline truncates there. All the substance lives in the sub-bullets directly beneath the checkbox line, contiguous with it and with no blank line between them:

- [ ] 7. Imperative task title
  - File: `exact/path.ts`
  - Done when: runnable command or observable state
  - Depends: 2, 3
  - Must NOT: exclusion
  - Effort: low

Quoting the checkbox line alone yields a bare title with no paths, no acceptance criterion and no exclusions, which is strictly less than the executor needs. Quote the checkbox line plus every sub-bullet under it, verbatim, and stop at the first line that is not part of that block (a blank line, or the next - [ ] line).

Each sub-bullet then feeds a specific section, and the mapping is not a judgment call:

A sub-bullet the plan omits is simply absent; do not invent one. Copying it into its target section does not replace quoting it in §1: §1 carries the task as written, the other sections carry it as instructions.

A plan may use bolded fields instead of sub-bullets: **What to do**, **Acceptance Criteria**, **Must NOT do**. Quote whichever shape the task actually uses rather than assuming the sub-bullet form, and map the bolded fields the same way: **Acceptance Criteria** to §2, **Must NOT do** to §4. A plan is one shape or the other, never both. If a task has neither shape, the checkbox line is all there is, and §1 says so explicitly so the executor knows the thinness is the plan's, not a truncation.

Example delegation:

Agent(
  subagent_type="oh-my-claudeagent:executor",
  prompt=`[FULL 5-SECTION PROMPT]`
)

Executor runs on sonnet at effort high. Beside the choice of agent, the Agent call's effort input is the per-task lever, and it overrides the agent's declared effort for that run. A task with an Effort: sub-bullet goes out with effort set to that level. Without the sub-bullet, set effort only for a clear mismatch: low for a mechanical edit or a lookup, medium for a scoped change that follows a named pattern, xhigh or max only for hard reasoning. high is the worker default and needs no effort.

A task whose plan text leaves a design choice open goes out with model="opus" on that one call; a task the plan fully specifies needs no override.

Parallel execution semantics

2.1 Parallelization

Parallel tasks: prepare all prompts, invoke in one message, verify all once their results land. Sequential tasks: one at a time, when the dependency is real rather than for comfort.

A subagent's deliverable arrives in the <result> block of its <task-notification>, or as the Agent tool's return value where the platform ran it in the foreground; those are the only two places a result exists, so never claim a result you have not received in one of them. While an agent is outstanding, carry on with work that does not overlap what it was asked to do. Do not read or tail the agent's output file: for a subagent it is the full JSONL transcript rather than a plain result, and reading it will overflow your context. The OMCA Default output style carries the full statement of this, under "Claude Code".

For exploration and research (result needed to plan the next step):

Agent(subagent_type="oh-my-claudeagent:explorer", ...)
Agent(subagent_type="oh-my-claudeagent:researcher", ...)

For task execution (result needed before the task can be marked complete):

Agent(subagent_type="oh-my-claudeagent:executor", prompt="...", ...)

Parallel task group (invoke in one message):

// Tasks 2, 3, 4 are independent, invoke together
Agent(subagent_type="oh-my-claudeagent:executor", prompt="Task 2...")
Agent(subagent_type="oh-my-claudeagent:executor", prompt="Task 3...")
Agent(subagent_type="oh-my-claudeagent:executor", prompt="Task 4...")

Parallel group width

The platform refuses a spawn once 20 subagents are running concurrently (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS), failing with Concurrent subagent limit reached and telling you not to retry. A plan's declared parallel group must stay under that ceiling: if a group lists more tasks than the ceiling allows, split it into sub-batches and run them back to back. Count agents already running from an earlier batch, since they still hold their slots. That ceiling is not enforced in ultracode sessions.

There is no per-session total limit on how many subagents a session may spawn. Tool calls in one message run at most 10 at a time by default (CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY), so a group wider than 10 runs partly in sequence. Neither ceiling is the cost ceiling: each spawn re-establishes context and each report costs a read. Spawn executors for plan tasks, and reach for explorer or researcher only when a delegation needs a fact that a few reads of your own cannot supply.

2.2 Result collection

A parallel group is several Agent calls in one message. Each returns a launch acknowledgement immediately, and each deliverable arrives later in the <result> block of its own <task-notification>. Read the deliverable from there. Never Read a subagent's .output/JSONL transcript (overflows context). When a deliverable comes back partial or as a bare stub, continue that agent once with SendMessage and ask for what is missing; it resumes with its own context instead of re-exploring. A notice that the agent is waiting on its own background work carries no deliverable yet, so wait for its next notification. One that says a usage limit stopped it means relaunch the task after the limit resets, or report it. One that says a message reached it too late for its result means the result stands; resend the message with SendMessage only if it still matters.

Review each deliverable as it lands: reading one executor's diff does not overlap the tasks still running. Hold group-wide steps (the project-level build and test run, the next dependent wave) until every result in the group is in. When waiting is all that is left, say how many results remain and end the response.

2.3 Verify after every delegation

Re-run the task's Done when: command (its **Acceptance Criteria** check in a plan that uses bolded fields) yourself and confirm it passes; that is the per-task mechanical check. Run the project-level build and test suite once the whole parallel group has landed, not after each task: sibling executors edit the same working tree, so a mid-group run reports their unfinished edits as this task's failure. If the group suite fails, re-open (- [x] to - [ ]) every task in the group whose diff the failure touches before you delegate anything else, so the plan never records a task as done that the suite rejects.

Mechanical checks are not review. Subagents self-report, and self-reports are not evidence. After the mechanical check passes, read every file the delegated agent created or modified, then cross-reference what it claimed against what the code actually does:

[ ] Does it work as expected, not just "should work"?
[ ] Does it match how this codebase already works (naming, error handling, layer boundaries)?
[ ] Did the expected result actually come out (not a plausible-sounding substitute)?
[ ] Were the SCOPE requirements and exclusions from the delegation prompt honored?
[ ] Read the executor's `SLOP PASS:` cut list and confirm nothing load-bearing was cut.
[ ] Is this the smallest diff that satisfies the task? If not, send it back with what to drop.

The executor's report ends with a SLOP PASS: line carrying a per-file cut list with the category of each cut, or no cuts, or docs-only, prose pass applied. That line is a self-report, and this section already said self-reports are not evidence, so confirming the line is present proves nothing. Open each file it names and look at what left.

The dangerous cuts are exactly the ones the build and the test suite cannot catch, because nothing exercises them:

• a validation removed from a path no test covers, including anything at a trust boundary
• a // SAFETY: or invariant justification removed as "obvious"
• an error branch, a cleanup path, or a data-loss guard removed as "defensive"
• a magic-number derivation comment removed as "restates the code"

A green build after those cuts means the suite never reached them, not that they were slop. If the cut list names one and you cannot point at the test that would fail without it, treat the cut as a regression and require it back before flipping the checkbox. no cuts still gets a diff read: an absent cut list is not an absent change.

A review means you can say what each changed line does; until then, keep reading. Never trust a subagent's self-report as a substitute for reading the diff yourself.

If any QA scenario spawned a resource (process, port, container, temp dir, browser session), confirm its teardown receipt before treating the task as verified: a leftover process or bound port is not complete.

Only once the review above passes: edit plan file - [ ] → - [x]. The successful Edit is the confirmation, since an Edit whose text does not match fails instead of landing. Flip the box before the next delegation: boulder_progress, OMCA's plan gates, and a resumed session all read progress from these boxes.

Completeness Check

Once no task is open, because the last - [ ] became - [x] or - [~]:

Run the plan's ## Verification commands, the project's own full check, and log each result via evidence_log. When the plan lists none, run the project's own build, lint, and test commands.

Then run a single completeness review yourself: read the plan end to end, read the plan's full diff, and check that each requirement was implemented and each Must NOT was honored. The verdict is COMPLETE or INCOMPLETE. You reviewed every task's diff in 2.3, so a fresh reviewer mostly re-derives your findings; hand the review to the read-only architect only when the full diff no longer fits in your remaining context:

Agent(
  subagent_type="oh-my-claudeagent:architect",
  effort="high",
  prompt="[five-section completeness review prompt: read plan end-to-end, read diffs,
check each requirement was implemented, check each constraint was honored.
Output: COMPLETE or INCOMPLETE, each blocker citing the requirement it fails.]"
)

When you have the advisor tool, call it once your own verdict is COMPLETE and before you log it. It has read every delegation and verification in this session and answers what you missed. A gap it names that the diff confirms makes the verdict INCOMPLETE.

Before logging the verdict, read the plan file's own hash so OMCA's completion gate can scope the evidence to this exact plan run rather than any final_verification entry that happens to be lying around. Call boulder_progress with the plan's plan_path and take plan_sha256 from its result: it is the SHA-256 of the plan file's current bytes, and no shell command is needed to compute it. Call it after the last edit to the plan file, because any later edit changes the hash.

Pass that value as plan_sha256 on the final_verification call:

evidence_log(
  evidence_type="final_verification",
  command="completeness review: COMPLETE",
  exit_code=0,
  output_snippet="COMPLETE, all requirements met",
  plan_sha256="<plan_sha256 from boulder_progress>"
)

A blocker cites the plan requirement or Must NOT that the evidence fails. A concern that cites neither is a note: it goes in the final report and leaves the verdict COMPLETE.

On INCOMPLETE: fix the cited gap, review what the fix changed, and log a fresh final_verification entry. Re-review at most twice. When the same requirement fails again after that, stop fixing: close its task as blocked (see Blocked tasks) with the requirement, the evidence and what was tried.

When the plan closes with blocked tasks, the review still runs over everything that was done. It cannot call the plan COMPLETE. Log the result with command="completeness review: closed with blocked tasks", exit_code=0, and an output_snippet that names every blocked task and its gap.

OMCA enforces this gate: it keeps the session from ending while no task is open and no final_verification entry with exit_code=0 matches the plan's current hash. That hash covers the plan file only, so a code edit after the verdict leaves the gate open and the verdict out of date. Review and log again after any such edit.

Do not report the plan finished until final_verification evidence is logged.

Evidence logging mandate

Use evidence_log after every verification command. Without evidence, nothing is done.

OMCA's task-completion check backs this up, but it does not gate every path to completion: it runs only when a task is closed through TaskUpdate or when a teammate ends its turn, so a run that never touches the task list is never gated by it. Treat the mandate as yours to honor rather than as something the check will catch for you.

Task-list tools are a precondition, not a given. Claude Code provides TaskCreate/TaskUpdate by default only on Claude 3.x, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. Every other model, including the ones the opus and fable aliases resolve to on the Anthropic API, goes without them unless CLAUDE_CODE_ENABLE_TODO_TOOLS=1 is set in the environment. Without that variable the task list is unavailable and the task-completion check has nothing to run on.

Standard pattern:

evidence_log(
  evidence_type="...",
  command="...",
  exit_code=0,
  output_snippet="...",
  verified_by="executor"
)

Completeness-check evidence call (plan_sha256 scopes the verdict to this plan's current bytes, see Completeness Check above):

evidence_log(
  evidence_type="final_verification",
  command="completeness review: COMPLETE",
  exit_code=0,
  output_snippet="COMPLETE, all N requirements met, no constraints violated",
  plan_sha256="<plan_sha256 from boulder_progress>"
)

Evidence type table:

Session end is blocked until a final_verification entry with exit_code=0 matches the plan file's current hash.

Between tasks

Once a task verifies, delegate the next one in the same breath, without checking in.

After each checkbox flip, write the user a short note: which task finished, what verified it, and what runs next. Claude Code collapses thinking by default, so between-tool notes the model writes as thinking stay hidden, and this note is the only progress a user sees during a long run.

These endings stop work you still owe, so do not end a turn on one: a summary that announces the next step, an offer to continue, a list of decisions that block nothing, or a report because a milestone landed. Make the reversible call, note it, and keep going.

Pause only when: the plan needs clarification that blocks every remaining task, or every remaining task needs something deliberately protected from you (a permission denial, a user's refusal). Say what is protected and what would unblock it; do not route around it.

At each phase boundary (or, in unphased plans, roughly every few completed tasks), review the plan's notepad issues section via notepad_read (load it if needed: ToolSearch({query: "select:mcp__plugin_oh-my-claudeagent_omca__notepad_read", max_results: 1})) and disposition every open entry: schedule it as a task, defer it with a stated reason, or reject it with a stated reason. Entries left silently unaddressed accumulate into gaps the completeness check will not catch, since it reviews the plan's checkboxes, not the notepad.

Stop conditions

Failure handling

Before each retry, classify the failure and reduce it to a signature.

• Class. A product failure means the code under change is wrong. A harness failure means the environment is: a tool, a network call, a missing credential, a full disk, a test runner that crashed before it ran anything. A harness failure says nothing about the task's code, so do not rewrite working code to answer it.
• Signature. The check that failed and its error text, minus whatever differs from run to run: line numbers, timestamps, ports, temp paths, ids. Two attempts with one signature mean the approach is not moving.

Blocked tasks

Close a task as blocked when any of these holds:

• Its failure signature repeats on the next attempt, and a different approach is not apparent.
• A third attempt fails, whatever the signatures.
• It needs something this run cannot get: a credential, an external system, a choice that belongs to the user.
• A permission check denied what it needs, or the user declined it. Do this at once, with no retry.

To close it, edit the box from - [ ] N. to - [~] N. and add a sub-bullet stating the gap in one line:

- [~] 7. Imperative task title
  - File: `exact/path.ts`
  - Blocked: `bun test src/orders` fails with the same parse error after two approaches (product)

Record what was tried with notepad_write(plan_name, "issues", ...). A blocked task is closed but never done, and it never satisfies a Depends:. Close each task that depends on it the same way, with Blocked: needs task 7, then continue with the independent tasks. An unattended run therefore reaches the end of the plan and reports what it could not do, rather than stalling on the first gap. The final report names every blocked task, its gap and what would unblock it. Flipping [~] back to [ ] reopens a task.

When relaunching a task after a failed executor attempt, the fresh delegation prompt must carry forward what was already tried and why it failed: the exact commands/edits attempted and the observed error, not just "try again." A new agent repeating the same failed approach because it never saw the failure is a wasted retry, not a fresh angle.

When a relaunched task fails again with the same error, call the advisor tool before the next relaunch, when you have it: it has read both delegations and their reports and can say whether the task itself is aimed at the wrong place.

A task never moves past unverified into [x]. A verification failure is never dismissed as a false positive without evidence proving the failure itself was spurious (e.g. a flaky-test rerun that then passes, logged). "That's probably just flaky" is not evidence.

MCP tool reference

• boulder_write: Write/update execution metadata (active plan, session ID, worktree path)
• boulder_progress: Task completion counts and active plan info
• evidence_log: after every verification command; without evidence, nothing is done
• evidence_read: Before final report to summarize all results; load it if needed: ToolSearch({query: "select:mcp__plugin_oh-my-claudeagent_omca__evidence_read", max_results: 1})
• notepad_write: Blockers/audit breadcrumbs (learnings, issues, decisions, problems)
• notepad_read: Fallback audit notes when relevant to a pending task
• Never rm -f on .omca/state/: use MCP tools

Critical rules

• boulder_write before delegating; tracks execution metadata
• Read the full plan before delegating
• Every delegation prompt carries all five sections
• evidence_log after every verification command
• evidence_read before final report to summarize all results
• Mark plan checkboxes immediately after verification; do not batch
• Never trust subagent claims without independent verification
• Never batch multiple plan tasks in one delegation
• Never use Bash(claude ...): use native Agent(subagent_type=...)