rlaope/oh-my-hermes / skills/ulw-plan
ulw-plan
Verified[omh] High-stakes technical proposal needing approval: consensus planning with review gates. Use when the user says: ralplan, consensus plan, reviewed plan, issue to PR, acceptance criteria, verification command, reviewable PR, risky planning.
Ralplan
This is a Hermes-native ralplan workflow skill.
Why This Exists
ralplan exists to make planning reviewable before execution: Hermes should gather codebase/source facts, compare options, expose risks, define acceptance criteria, and prepare a handoff without pretending implementation already happened.
First Steps
- Initialize the plan todo before the first planning step: declare the planning stages as
omh_todoitems (todo init), never also intodo_list— repo facts and evidence check, options and tradeoffs, risk review, acceptance criteria and verification commands, plan record and acceptance — keep exactly one item active, and when the evidence check reveals a gap rewrite the list (omh_todoaction=set) to insert the research stage; update the list as stages complete so the HUD todo panel shows plan progress as a bounded checklist, and treat items as declarations, never execution evidence. Phase names and task titles are written in English — short, operator-legible labels — even when the conversation runs in another language, since the HUD todo checklist is an operator surface under the repo's English-by-default output contract.
Do Not Use When
- The request is still too ambiguous to name requirements, non-goals, or acceptance criteria; use
ulw-interviewfirst. - The user asks for one full research-plan-implementation-review-PR cycle; use
ulw-work(itsdelivery_boundarycapability) and keep ralplan as the planning stage. - The change is a small local refactor or cleanup with no architectural or regression risk; use
ulw-work, oromh-ai-slop-cleanerwhen observable behavior must stay identical. - The refactor's direction is already decided and what is missing is its execution shape - which files move in which phase, what verifies each phase, where each phase rolls back to; use
omh-refactor-plan. - One plan-blocking choice still needs behavior evidence rather than argument; run
omh-decision-prototypefirst and consume its decision receipt without transcript replay. - The user wants a pure source lookup, citation check, or paper explanation with no implementation plan.
- An ordinary feature or fix that needs a plan but not a consensus review (no architectural, regression or user-visible risk the user named); use
omh-plan. - The unresolved work is repository terminology alignment or a project-language decision frontier; use
ulw-contextbefore planning.
Examples
Good example:
- Prompt: $ralplan turn this risky refactor into a reviewable plan with acceptance criteria and verification commands.
- Expected behavior: Produce repo/source facts, alternatives, risk review, acceptance criteria, exact verification commands, and handoff readiness without editing code.
- Why: The request is clear enough to plan but risky enough to require consensus-style review before execution.
Bad example:
- Prompt: $ralplan implement the refactor now and open the PR.
- Expected behavior: Stop at the reviewed plan or route the full delivery cycle to
ulw-workafter plan acceptance. - Why: Ralplan is a planning gate, not implementation, review, CI, or PR evidence.
Completion Checklist
- The plan todo was declared before the first planning step and every stage reached a terminal state; a plan produced without one, or with stages still pending, is not finished.
- Observed repo facts and source/web evidence gaps are named.
- At least two options or one chosen option plus rejected alternatives are recorded.
- Risks, acceptance criteria, and verification commands are testable or explicitly blocked.
- Every target-state difference has a
Success criteriarow with a task and a verification scenario or is recorded as a user-excluded non-goal, and theTarget-state coveragecheck left none unmapped: the plan states the count of target-state differences and the count ofSuccess criteriarows, and the two are equal or each gap is named as a user-excluded non-goal. - When the plan describes code changes, it names the goal beyond the request, the raw material, and an outside judge for each verification step, or records the missing judge as an evidence gap.
- The plan exists as a recorded file-backed artifact, not only as chat narration.
- The implementation handoff is prepared only after plan acceptance and remains prepared_not_observed.
- The follow-on engine or executor path was started only after the user's explicit go-ahead in this conversation, never from plan acceptance alone.
Recovery Notes
- If requirements are still fuzzy, route back to the
ulw-interviewworkflow before planning. - If current-source evidence is missing, route a
ulw-researchstep before accepting the plan. - If the user asks for implementation after acceptance, recommend the follow-on path that fits the work's shape (
dag-ulwwhen the accepted lanes form a graph with a verification lane,ulw-workwith the matching capability — durable checkpoint, coordinated lanes, single-owner persistence, or one delivery cycle — or a direct selected executor handoff) with a one-line fit reason, and start it only on the user's explicit go-ahead — never auto-start an engine from acceptance alone.
Workflow Lane
- Current lane: Intent -> plan - clarify, plan, ship, or loop goals.
- If intent belongs to another lane, hand back to
omh-routingor name the adjacent workflow. - Shared product, routing, compatibility, and evidence rules:
skill_view(name='omh-routing', file_path='references/skill-common-rail.md').
When to Use
Use when requirements are clear enough for planning but architecture, evidence, alternatives, risks, or tests need a reviewed plan before execution.
Strong routing signals: `ralplan`, `$ralplan`, `consensus plan`, `reviewed plan`, `issue to PR`, `acceptance criteria`, `verification command`, `reviewable PR`, `risky planning`, `dangerous planning`, `unsafe change`, `refactor safety`, `PR로 만들`, `PR로 만들 수 있게`, `위험한 리팩터링`, `리팩터링 위험`, `리스크 있는 리팩터링`, `검증 command`, `리뷰 가능한 단위`, `코드베이스 조사`, `웹리서치 계획`, `대안 비교`, `리스크 검토`, `план с рисками`, `план с критериями приёмки`, `рискованный рефакторинг`, `опасный рефакторинг`
Catalog Metadata
Category: planning
Phase: reviewed-plan
Hermes role: planner
Quality tier: reviewed-plan-gated
Reasoning demand: standard
Quality bar:
- Start from observed repo facts and source/web evidence when freshness or external behavior matters.
- Include planner view, critic/risk review, alternative paths, rejected options, and a testability check before handoff.
- Produce testable acceptance criteria and exact verification commands or explain why they are not yet knowable.
- List every lane of the accepted plan in node-prompt shape -
TASK,DELIVERABLE,SCOPE,VERIFY,STOP WHEN- withdepends_onper lane, sodag-ulwnodes orulw-workboard rows come from the plan without re-planning; planning itself stays a bounded in-session lane. - When a planning stage dispatches a planner or critic child, set
omh_delegate_routewith categoryultrabrainin the same turn, before thatdelegate_task, and clear it (omh_delegate_routeactionclear) once those children are dispatched. - When adapting an existing capability, load
skill_view(name='omh-verification-gate', file_path='references/adaptation-quality.md')before accepting a plan, dispatching work, or claiming completion; carry its criteria and comparisons into tasks and evidence. - Before comparing options, write the target state: name each consumer of the result (a person, a maintainer, or a program reading its output), their current workflow on this surface, the state in which that workflow keeps working with no new friction or loss, and every difference between current and target, each with why it matters.
- Record a
Success criteriatable with columnsCriterion | Task | Verification scenario, one row per target-state difference naming its owning task and the scenario that shows the difference closed; these rows are the acceptance criteria above, extended to the target state. - End with a
Target-state coveragecheck: a difference with no owning task or no verification scenario is added to the plan as its own task, unless the user excluded it, in which case the plan records it as a non-goal with that reason; a difference blocked on missing evidence stays in the evidence-gap record below instead. - Never shrink scope on your own: plan an MVP or a first phase only when the user requested one, plan a split or phasing the user requested as given, and when the target state exceeds what was literally asked, state that in one sentence and plan the full target state.
- Size each task as one band, never as hours or days:
XS(one small edit),S(one file and its test),M(several files in one module),L(several modules or one contract change),XL(crosses subsystems; split it into smaller tasks). - When the plan describes code changes, name the goal beyond the request before splitting tasks: one sentence on what should happen once the requested result exists, and whether the plan aims at that outcome or at the request as asked; when the two are the same, say so in one line. A plan aimed at the outcome adds, as its own tasks, the access the executor needs to work at that level unattended - failure logs, a reproduction environment, the raw data, the mapping from a released version to its commit.
- When the plan describes code changes, name the raw material the work starts from instead of a digest of it - the failing log, trace, or data rather than the issue summary - and the methods and tools a leading practitioner of the field would use on it. Every verification step names an outside judge - a test, CI, a measurement, a human reviewer, or an external tool - never the planning model's or the executor's own reading of the result; a step with no outside judge is recorded as an evidence gap.
- When the plan describes code changes, restate the deliverable once as the verbs it must accomplish rather than the noun it produces; when that brings in another field, write what a practitioner of that field does as a task (fuzz the parser, audit each completion claim against its evidence), never an instruction to write or speak like one.
- Record unresolved tradeoffs and evidence gaps instead of flattening uncertainty.
- When plan-shaping evidence is missing — current external behavior, contested claims, or unstudied reference implementations — run the
ulw-researchworkflow as a bounded in-plan stage (not an exhaustive deep-research run) before comparing options, record its dossier the way theulw-researchartifact contract requires, and consume it instead of planning on assumptions. - Consume a recorded
ulw-researchdossier when one exists: plan options and rejected alternatives should cite its decision drivers and verified claims. - Take plan acceptance only from the answer the user gave — the response status and value the question tool returns, or the user's own reply — never from the wording of the question you asked: when the acceptance question times out, is dismissed, or returns with no answer, the plan stays unaccepted, so record no acceptance, prepare no handoff, and start nothing; a missing answer is not a refusal either, so ask again later or report the plan as awaiting acceptance.
- End with a selected executor/runtime handoff shape only after the plan is accepted.
- Plan acceptance approves the plan content, not execution: after acceptance, recommend the follow-on path that fits the work's shape —
dag-ulwfor an accepted plan whose tasks form a graph (several tasks with disjoint write scopes or an order between them, handing work on through files, plus a separate verification task),ulw-workdurable checkpoints for progress that must survive sessions as a checkpointed ledger,ulw-workcoordinated lanes for an accepted plan split into disjoint parallel lanes,ulw-worksingle-owner persistence for one already-scoped task with a single owner,ulw-workfor one bounded delivery cycle, or a direct selected executor/runtime handoff for a single prepared coding change — state the fit reason in one line, and start it only after the user's explicit go-ahead. - Do not implement directly from consensus planning.
Handoff policy:
Keep consensus planning and review in Hermes; produce explicit selected executor/runtime handoff guidance only after the plan is accepted, and start a follow-on workflow engine only after the user explicitly confirms the recommended path.
Required inputs:
- requirements
- codebase facts
- source or web evidence when needed, or an in-plan research stage to obtain it
- options
- tradeoffs
- test shape
Expected outputs:
- reviewed plan
- acceptance criteria
- risk register
- verification commands
- handoff guidance
Artifact expectations:
- write the reviewed plan (options, rejected alternatives, risks,
Success criteriatable, target-state coverage, lanes in node-prompt shape) to a Markdown file outside the repository and the OMH store (the system temp directory is fine), then record it withomh hermes plan --record --plan-file <file> "<task>", which writes<repo>/.omh/plans/<slug>.mdinside a repository and the user-scope OMH store outside one; without--plan-filethe file holds only a generated scaffold, and itssayfield tells you so - mark acceptance with
omh hermes plan-accept <path>only for a file recorded with--plan-file(front matterplan_body: reviewed), so acceptance_recorded and handoff_ready point at the reviewed plan;plan-acceptrefuses a scaffold-only file, and--allow-scaffoldaccepts the scaffold only when the user asked for that, not a reviewed plan
Safety rules:
- Do not implement directly from the planning lane.
- Do not invent codebase or web evidence; label missing evidence and source gaps.
- Make acceptance criteria testable.
- Record unresolved tradeoffs explicitly.
- Keep rejected options and handoff readiness separate from accepted execution evidence.
- Record plan artifacts only through the named
omh hermes plancommands (the reviewed text goes in through--plan-file, not by editing the recorded file) under<repo>/.omh/plans/; never write plans or planning state into.omc/**or any other wrapper's state root —.omc/belongs to oh-my-claudecode, a different product.
Runtime Evidence
Preferred harness for this skill: planning.
omh runtime record --skill ralplan --harness planning --status started
Record observed delegation results; otherwise return not_available or not_observed.
Prepared OMH routing is not execution, review, CI, merge-readiness, or merge evidence.
- When wrapper metadata includes
memory_review_card/v1orhandoff_context_pack/v1, treat it as reviewed OMH-local or wrapper-supplied context only. Use conflict-free context summaries to shape plans and handoffs, but do not claim Hermes internal memory was read or changed. Preserve workflow intent and stop conditions; verify before claiming completion. Reply in the user's own words and the host's own voice: its SOUL.md persona owns reply language, tone, speech level, and sentence endings, progress updates included (where it sets no language, use the one the user wrote in), and OMH shapes structure and content only. When the requested output is delivered, put any open points inside the result and end with no question or offer; only when the person asked to choose or decide and that choice is still theirs, end with one specific question about it, not a list, a generic offer, or a footer; the shared rail's Reply Language And Host Voice and Turn Ending sections hold the full rule.
Use Hermes-native subagent/delegation features when available: native subagents -> Hermes delegation when available, otherwise sequential lanes.
Shared product, compatibility, topology, memory, harness, and execution rules: skill_view(name='omh-routing', file_path='references/skill-common-rail.md'). Load it when applicable; otherwise name an unavailable capability.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |