Ultragoal

1. Create a plan from a brief:

   omc ultragoal create-goals --brief-file plan.md
   

   Or with explicit stories:

   omc ultragoal create-goals --brief "ship the migration" \
     --goal "Schema::Add new columns" \
     --goal "Backfill::Backfill rows in batches" \
     --goal "Cutover::Drop old columns and switch reads"
   

   The default mode is aggregate (one Claude /goal covers the run). Pass --claude-goal-mode per-story if you want each story to have its own /goal.

   Multi-repo workspaces / parallel sessions: when several Claude sessions in the same workspace need to run /ultragoal concurrently, pass either --plan-id <stable-id> or --auto-plan-id so the plan is written to .omc/ultragoal/plans/{planId}/ instead of the shared single-plan path. Without that flag, two sessions creating goals would clobber each other. --auto-plan-id derives {epochMs}-{slug} from the brief title. Then thread the same --plan-id <id> through every subsequent subcommand in that session. Use omc ultragoal list-plans to enumerate available planIds when needed.

2. Start (or resume) the next story:

   omc ultragoal complete-goals [<goal-id>]
   

   With no goal id, this preserves the default behavior of resuming the active story or starting the first pending story. With a goal id, OMC targets exactly that named eligible story (a pending story may be started out of order); it never falls through to another story. An active different story, unknown id, completed or review-blocked story, or failed story without --retry-failed is rejected without state mutation. An in-progress named story is resumed without changing its attempt. This prints a model-facing handoff. The active Claude agent must read it and:

   • Set the native Claude /goal for this session — in standalone Claude Code neither the shell nor the agent can do it, so ask the user to type /goal <aggregate objective> and wait. --claude-goal-json (below) reconciles the ledger only and does not satisfy the PreToolUse /goal guard, which blocks tool calls until it observes an active /goal.
   • Work the story.
   • When the story is complete (and for the final story, after the full quality gate), share back a snapshot of the active /goal state and call checkpoint.

3. Checkpoint a story:

   omc ultragoal checkpoint --goal-id G001-... --status complete \
     --evidence "tests/files/PR evidence" \
     --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'
   

   For the final story, also pass --quality-gate-json containing aiSlopCleaner, verification, and codeReview evidence (all clean).

4. If the final review is not clean, do NOT mark complete. Record blockers:

   omc ultragoal record-review-blockers --goal-id G00X-... \
     --title "Resolve final code-review blockers" \
     --objective "Fix the listed review findings and rerun final gates" \
     --evidence "<the review findings>" \
     --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'
   

   This appends a new blocker story and keeps the Claude /goal active.

5. Inspect state at any time:

   omc ultragoal status
   

Parallel session caveats

• Multi-repo workspace anchor: drop a .omc-workspace marker at the parent directory so multiple sessions across sub-repos share one .omc/. Resolution order: OMC_STATE_DIR > .omc-workspace > git > cwd. See docs/REFERENCE.md.
• Session id source: OMC_SESSION_ID env var wins in CLI contexts; hook payload data.session_id wins in hook contexts.
• Plan id (when applicable): Two runs in the same workspace will conflict on shared plan artifacts. Use distinct session IDs (the hook payload session_id is already isolated per Claude Code session), or pass --plan-id to keep parallel ultragoal runs on separate ledgers.
• Parallel verdict: supported (each session writes its own session-scoped state)