code-yeongyu/oh-my-openagent / packages/omo-codex/plugin/components/ultrawork/skills/ulw-plan
ulw-plan
VerifiedACTIVATES ONLY on an explicit user request for the ulw-plan workflow: the user themselves saying ulw-plan, ulw plan, /skill:ulw-plan, or asking in their own words for a work plan before coding. NEVER self-activates: a bare ulw/ultrawork run, an agent-side routing decision, or reading this file is not a request, and the plan-gated reviewers (metis/momus) stay locked without a user request plus a written .omo/plans plan file. Explore-first planning consultant (Prometheus) that grounds in the codebase, asks only the forks exploration cannot resolve - or researches them to best practice when the intent is fuzzy - waits for explicit approval, then writes ONE decision-complete work plan a worker executes with zero further interview. Triggers: ulw-plan, ulw plan, plan this, make a plan, plan before coding, interview me, break this down, start planning, plan mode.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.4 KB |
| agents/openai.yaml | config | 323 B |
| references/full-workflow.md | markdown | 31.0 KB |
| references/intent-clear.md | markdown | 5.1 KB |
| references/intent-unclear.md | markdown | 6.7 KB |
| scripts/plan-templates.mjs | script | 7.3 KB |
| scripts/scaffold-plan.mjs | script | 8.4 KB |
scripts/scaffold-plan.mjs
View on GitHub#!/usr/bin/env node
// scaffold-plan.mjs - generate the ulw-plan draft + plan skeleton deterministically.
//
// Zero external dependencies (node:fs/path/process/url builtins only) so it runs
// byte-identically under `node` and `bun` on macOS, Linux, and Windows with no uv
// bootstrap, no npm/pip install, and no POSIX-shell or python3 precondition - the
// two things genuinely not guaranteed on native Windows across the omo harnesses.
//
// Usage: node "<skill-root>/scripts/scaffold-plan.mjs" <slug> [--clear|--unclear] [--draft-only] [--review-required] [--reset [--force]]
//
// RESUME-SAFE: run it ONCE at plan generation. A plain re-run on an existing
// ulw-plan artifact is a NO-OP success (it never overwrites your appended todos),
// so a model resuming after compaction cannot crash the turn or clobber the plan.
// Destructive overwrite is reserved behind --reset, and --reset refuses to discard
// a hand-edited file unless --force is also passed.
//
// WRITE BOUNDARY: the prometheus-md-only hook gates Write/Edit but NOT Bash, so
// this node:fs script writes out of band of that hook. It self-guards THIS script's
// own writes to resolve under .omo/ (it does not, and cannot, contain other Bash
// commands; it only guarantees the mandated generator never escapes .omo). Mirrors
// packages/omo-opencode/src/hooks/prometheus-md-only/path-policy.ts.
import { lstat, mkdir, writeFile, readFile, realpath } from "node:fs/promises";
import { dirname, join, relative, resolve, isAbsolute } from "node:path";
import { pathToFileURL } from "node:url";
import { FINAL_VERIFICATION_ITEMS, PLAN_SECTION_HEADERS, buildDraft, buildPlanSkeleton } from "./plan-templates.mjs";
// The emitted text lives in plan-templates.mjs; re-exported so importers keep one entry point.
export { FINAL_VERIFICATION_ITEMS, PLAN_SECTION_HEADERS, buildDraft, buildPlanSkeleton };
const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,79}$/;
export function parseArgs(argv) {
const rest = argv.slice(2);
let slug;
let intent = "unspecified";
let force = false;
let reset = false;
let draftOnly = false;
let reviewRequired = false;
for (const arg of rest) {
if (arg === "--clear") intent = "clear";
else if (arg === "--unclear") intent = "unclear";
else if (arg === "--reset") reset = true;
else if (arg === "--force") force = true;
else if (arg === "--draft-only") draftOnly = true;
else if (arg === "--review-required") reviewRequired = true;
else if (arg.startsWith("--")) throw new Error(`unknown flag: ${arg}`);
else if (slug === undefined) slug = arg;
else throw new Error(`unexpected argument: ${arg}`);
}
if (!slug) throw new Error('usage: scaffold-plan.mjs <slug> [--clear|--unclear] [--draft-only] [--review-required] [--reset [--force]]');
if (!SLUG_PATTERN.test(slug)) {
throw new Error(`invalid slug "${slug}" - use lowercase letters, digits, and hyphens only`);
}
return { slug, intent, reset, force, draftOnly, reviewRequired };
}
// Resolve a project-relative path and confine it under .omo/ - the script's own
// enforcement of the prometheus planner write boundary.
export function resolveSafeOmoPath(cwd, relPath) {
const resolved = resolve(cwd, relPath);
const rel = relative(cwd, resolved);
if (rel.startsWith("..") || isAbsolute(rel)) {
throw new Error(`refused: path escapes the workspace root: ${relPath}`);
}
if (!/(^|[/\\])\.omo([/\\]|$)/i.test(rel)) {
throw new Error(`refused: ulw-plan may only write under .omo/: ${relPath}`);
}
if (!resolved.toLowerCase().endsWith(".md")) {
throw new Error(`refused: ulw-plan may only write .md files: ${relPath}`);
}
return resolved;
}
function assertContainedPath(parent, child, message) {
const rel = relative(parent, child);
if (rel.startsWith("..") || isAbsolute(rel)) {
throw new Error(message);
}
}
async function mkdirWithoutSymlinks(dir, stopAt) {
if (dir === stopAt) return;
const parent = dirname(dir);
if (parent === dir || relative(stopAt, dir).startsWith("..") || isAbsolute(relative(stopAt, dir))) {
throw new Error(`refused: path escapes the workspace root: ${dir}`);
}
await mkdirWithoutSymlinks(parent, stopAt);
const stat = await lstat(dir).catch((err) => {
if (err && err.code === "ENOENT") return null;
throw err;
});
if (stat) {
if (stat.isSymbolicLink()) {
throw new Error(`refused: path component is a symlink: ${dir}`);
}
if (!stat.isDirectory()) {
throw new Error(`refused: path component is not a directory: ${dir}`);
}
return;
}
await mkdir(dir);
}
async function assertSafeWriteParent(cwd, target) {
const workspaceReal = await realpath(cwd);
const workspaceRoot = resolve(cwd);
const omoRoot = resolve(cwd, ".omo");
const parent = dirname(target);
assertContainedPath(workspaceRoot, parent, `refused: path escapes the workspace root: ${target}`);
assertContainedPath(omoRoot, parent, `refused: ulw-plan may only write under .omo/: ${target}`);
await mkdirWithoutSymlinks(parent, workspaceRoot);
const omoReal = await realpath(omoRoot);
const parentReal = await realpath(parent);
assertContainedPath(workspaceReal, parentReal, `refused: path escapes the workspace root through symlinks: ${target}`);
assertContainedPath(omoReal, parentReal, `refused: ulw-plan may only write under .omo/ through real paths: ${target}`);
}
async function assertSafeWriteTarget(target) {
const stat = await lstat(target).catch((err) => {
if (err && err.code === "ENOENT") return null;
throw err;
});
if (stat?.isSymbolicLink()) {
throw new Error(`refused: target is a symlink: ${target}`);
}
}
// A file this script previously emitted (plan skeleton or draft), used to make a
// plain re-run a safe no-op instead of a crash or a clobber.
export function isUlwArtifact(content) {
const isPlan = content.includes("## TL;DR (For humans)") && content.includes("## Final verification wave");
const isDraft = content.includes("# Draft:") && content.includes("## Approval gate");
return isPlan || isDraft;
}
// Resume-safe write: plain re-run on an existing ulw-plan artifact is a no-op
// success; --reset overwrites but refuses to discard a hand-edited file unless
// --force is also passed.
export async function writeGuarded(cwd, relPath, content, { reset = false, force = false } = {}) {
const target = resolveSafeOmoPath(cwd, relPath);
await assertSafeWriteParent(cwd, target);
await assertSafeWriteTarget(target);
const existing = await readFile(target, "utf8").catch(() => null);
if (existing && existing.trim() !== "") {
if (!reset) {
if (isUlwArtifact(existing)) return { relPath, status: "exists" };
throw new Error(`refused: ${relPath} exists and is not a ulw-plan artifact (pass --reset to overwrite)`);
}
if (existing.trim() !== content.trim() && !force) {
throw new Error(`refused: ${relPath} has edits that differ from a fresh skeleton; pass --reset --force to discard them`);
}
}
await writeFile(target, content, "utf8");
return { relPath, status: existing ? "reset" : "created" };
}
export async function scaffold(cwd, { slug, intent, reset = false, force = false, draftOnly = false, reviewRequired = false }) {
const draftRel = join(".omo", "drafts", `${slug}.md`);
const draft = await writeGuarded(cwd, draftRel, buildDraft(slug, intent, { reviewRequired }), { reset, force });
if (draftOnly) return [draft];
const planRel = join(".omo", "plans", `${slug}.md`);
const plan = await writeGuarded(cwd, planRel, buildPlanSkeleton(slug, intent), { reset, force });
return [draft, plan];
}
async function main() {
const { slug, intent, reset, force, draftOnly, reviewRequired } = parseArgs(process.argv);
const results = await scaffold(process.cwd(), { slug, intent, reset, force, draftOnly, reviewRequired });
for (const r of results) process.stdout.write(`${r.status}: ${r.relPath}\n`);
const created = results.some((r) => r.status !== "exists");
process.stdout.write(
draftOnly
? `next: record intent, findings, decisions, review state, and the approval gate in the draft; create the plan only after approval.\n`
: created
? `next: record findings/decisions in the draft, then APPEND task batches into the "## Todos" region of the plan; fill "## TL;DR (For humans)" LAST.\n`
: `skeleton already present - left untouched. APPEND task batches into the "## Todos" region; the human "## TL;DR (For humans)" stays on top.\n`,
);
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
await main().catch((err) => {
process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
process.exit(1);
});
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |