zvadaadam/az-skills/plan-for-mega-goal

Plan for Mega-Goal

For work that's bigger than one goal but smaller than an unbounded backlog. Produces a roadmap folder on disk that survives the loop, plus a short pointer prompt to paste into /goal. The loop reads the roadmap every turn; the pointer prompt stays tiny.

The Topic

$ARGUMENTS

When to use this vs plan-for-goal

Almost always start with plan-for-goal. Reach for this skill only when:

• The work has 3+ genuinely independent objectives that share a destination and a quality bar, AND
• Collapsing them into one prompt would either lose load-bearing information or blow past 4000 chars.

If you can't name 3+ distinct sub-goals each with their own Done = line, this is one goal — go back to plan-for-goal. A flat list of unrelated tasks isn't a mega-goal either; those are separate goals to run separately. A mega-goal has one shared destination, multiple paths to it.

How this rides on top of /goal

/goal is one-objective-per-thread (codex enforces this at the data layer) and caps the user-typed objective at 4000 characters. But its continuation template explicitly treats "any referenced files, plans, specifications, issues, or user instructions" as a source of requirements for the completion audit. We use that mechanism: the pointer prompt is short and points at a roadmap file; the roadmap holds the multi-goal structure; the completion audit walks the roadmap.

Each sub-goal inherits from plan-for-goal

Every file under goals/ IS a plan-for-goal output — same anchors (Goal, What great looks like, How to close the loop, Done =, Not, Open, Where to look), same labels, same rules. Read `../plan-for-goal/SKILL.md` first. This skill governs only how sub-goals fit together as a system, not how each individual one is written.

Delegation, not duplication. references/subgoal-template.md describes only the deltas: four rule overrides (4000-char cap doesn't apply to disk files; "one objective" applies per sub-goal; the pointer prompt is allowed one exact path; Done = / close-the-loop must be PR-specific and sub-goal-specific) plus two mega-goal-specific additions (Time budget: and ## PR body). Updates to plan-for-goal's anchors, labels, or rules flow through to mega-goal sub-goals automatically — sharpen plan-for-goal, every mega-goal benefits.

What you produce

On disk, committed to the repo (the roadmap is engineering record-of-work, not ephemeral):

.megagoal/<slug>/
├── ROADMAP.md            # checkbox list — source of truth for what's done, records PR #s
├── POINTER_PROMPT.md     # the exact text pasted into /goal — durable + resumable
├── NOTES.md              # three sections: Active blockers (in place) · Proposed additions · Event log
├── FEEDBACK.md           # append-only meta-feedback for improving the skill / tooling / codebase
└── goals/
    ├── 01-<slug>.md      # one plan-for-goal-shaped file per sub-goal
    ├── 02-<slug>.md
    └── ...

`FEEDBACK.md` is the meta layer — append-only observations the agent records during the run about friction in the skill, missing tooling, or codebase issues that complicated the work. The audience is the skill maintainer (you), not the loop runner. After the run, you skim FEEDBACK.md and decide which items to fold back into plan-for-mega-goal, related tooling, or the codebase as separate work. See references/feedback-template.md. Without this, every mega-goal run's lessons evaporate; with it, the skill gets sharper with every use.

`ROADMAP.md` records PR numbers as soon as they exist, not just when boxes get checked: - [ ] — PR #117 for in-progress sub-goals, - [x] — PR #117 for complete. This makes ROADMAP.md the canonical lookup for "what PRs belong to this stack" — no fragile branch-name search needed.

`POINTER_PROMPT.md` holds the raw prompt (no markdown wrapper) — cat .megagoal/<slug>/POINTER_PROMPT.md | pbcopy regenerates the clipboard so the user can resume the loop hours or days later from any machine. It's also the durable record of "what spec was the loop actually running under" — without it, the prompt only lives in /goal's thread-scoped SQLite and dies when the thread ends.

`NOTES.md` has structured sections with different update semantics — ## Active blockers is updated in place (no duplicate stop summaries), ## Proposed additions is append-only, ## Event log is append-only. See references/notes-template.md. Without this structure, every resume of a blocked loop appends another identical stop summary to NOTES.md — noise that obscures the real event log.

The pointer prompt — the only thing the user pastes into /goal. It encodes how the loop runs autonomously for hours or days without human intervention: how to pick the next sub-goal, how to handle review feedback / CI failures / stack-tool conflicts inline, the discipline rules, and the genuine stop conditions. Under 4000 chars (codex's hard cap). See references/examples.md for the full form.

How to use it

1. Pre-flight: detect the loop's required tools — but don't block on missing ones. The /goal loop needs:

• `gh` (GitHub CLI) — for PR creation, status checks, reading reviewer comments.
• `ghstack` — to manage the stacked PRs.

Run which gh ghstack to detect what's installed locally. Do not attempt to install missing tools yourself — that crosses too many trust boundaries (system paths, network, possibly sudo).

Don't stop the plan if something's missing locally. The planning agent and the /goal loop may run in different environments — the user may invoke /plan-for-mega-goal in Claude Code on one machine and paste the prompt into /goal on another. Local detection is necessary but not sufficient. Note what was missing (if anything) and surface it as a prominent install-first banner when you show the pointer prompt in step 7.

The pointer prompt itself MUST include a turn-1 pre-flight that re-runs which gh ghstack and stops the loop if either is missing — that's defense in depth and catches the cross-environment case.

Why ghstack and not Graphite (`gt`) or `spr`: open source, single-command install, pure Python, battle-tested at scale (PyTorch). The skill's pointer-prompt template uses ghstack commands; if you have a strong preference for another stack tool, swap the commands manually after scaffolding. The default opinion is ghstack.

1. Decompose first, confirm, *then* write. Read the conversation. Draft a sub-goal list (typically 3–8 items — fewer and it's one goal, more and the loop loses coherence). For each one: a name, a one-line Done =, and any dependencies on other sub-goals. Show this to the user as plain text before touching disk. The wrong decomposition is the most expensive failure mode — fix it before scaffolding.

1. Pick the `<slug>` as a short kebab-case noun for the whole mega-goal (e.g. auth-rewrite, pricing-page, eval-harness). State it to the user.

1. Write the scaffolding once approved. Create .megagoal/<slug>/ at repo root with:

• ROADMAP.md per references/roadmap-template.md
• sub-goal files in goals/ (numbered 01-…, 02-…) per references/subgoal-template.md
• NOTES.md pre-scaffolded with three section headers (## Active blockers, ## Proposed additions, ## Event log) per references/notes-template.md
• FEEDBACK.md pre-scaffolded with the header and category list per references/feedback-template.md

Don't leave NOTES.md or FEEDBACK.md empty — the loop needs the section structure to know where to write. POINTER_PROMPT.md gets written in step 6 after the prompt is measured.

1. Each sub-goal file follows `plan-for-goal`'s 5 anchors with the overrides in references/subgoal-template.md. Sub-goal files can be longer than 4000 chars — they're read from disk, not injected. Keep them tight anyway; padding compounds across the loop.

1. Measure the pointer prompt AND write it to disk. Pipe through wc -m to verify under the 4,000-char hard cap. State the count to the user in one line above the code block — e.g. "Pointer prompt: 3,595 chars — under the 4000 cap." If you're at 3,000–4,000, audit what's there: hard constraints that prevent observed failure modes (good — keep) vs. step-by-step recipes specifying exact retry counts, exact time intervals, exact command flags (micromanaging — trim). The reference pointer prompt in references/examples.md is ~3,600 chars and earned every line by preventing real failure modes — but don't pad to match it.

Then save the exact prompt to `.megagoal/<slug>/POINTER_PROMPT.md` as raw text (no markdown wrapper, no banner — the banner is human-facing context, not the prompt itself). This makes the prompt durable: someone returning days later can cat .megagoal/<slug>/POINTER_PROMPT.md | pbcopy to regenerate the clipboard and resume /goal without needing to find the original conversation.

1. Copy the pointer prompt to the clipboard, then show it. Output shape: a prominent install-first warning banner FIRST, then the pointer prompt in a fenced code block. The banner is non-negotiable — the worst-observed failure mode is the user pasting the prompt into a /goal loop where ghstack isn't installed, resulting in a 34-minute autonomous run that produces a single local change set and zero PRs. Visibility-first prevents this.

Banner template (adjust the emphasis based on what was detected in step 1):

> ⚠️ INSTALL REQUIRED BEFORE PASTING INTO `/goal` ⚠️ > > The autonomous loop needs these installed in whatever environment runs `/goal` (not just where you ran /plan-for-mega-goal): > - `gh` (GitHub CLI) — brew install gh && gh auth login > - `ghstack` — pip install ghstack && ghstack auth > > Without these, the loop will produce a single local change set instead of a stacked PR series. The pointer prompt's turn-1 pre-flight catches missing tools and stops the loop, but the banner prevents the wasted-time failure mode upstream. > > Also: codex has no pause primitive. /goal only has "complete" (which the loop won't trigger while sub-goals remain unfinished) or "continue". If the loop becomes blocked on external prerequisites (PR not yet merged, workflow not yet on default branch, missing credential, human gate), you'll see repeated 🛑 LOOP BLOCKED messages — that means it's waiting on you. Stop `/goal` manually from your harness. Re-paste .megagoal/<slug>/POINTER_PROMPT.md once a prerequisite changes.

If step 1 found something missing locally, sharpen the banner: e.g. "You currently have `gh` but not `ghstack` here — install before pasting, or ensure it's installed wherever you run `/goal`."

1. If the loop drifts later, edit `ROADMAP.md` or a sub-goal file directly — the loop re-reads them every turn. Don't patch the pointer prompt; the prompt is just a pointer, the roadmap is the lever.

What the pointer prompt must encode

The pointer prompt frames the work for hours or days without human intervention. It gives the agent the shape of autonomous operation while trusting the agent's judgment for tactical decisions. The skill is a track, not a remote control — describe the shape, define the few autonomy boundaries, and let the agent handle the rest.

Hard constraints

These are autonomy boundaries AND the workflow shape itself, not productivity tactics. The skill exists to enforce them. The pointer prompt must phrase them as rules with no softening language — agents will rationalize around constraints that read like "good defaults".