@opellen/opengoal 1.0.0

package/templates/commands/scout.md

@@ -0,0 +1,89 @@
+---
+name: "opengoal:scout"
+description: "Project scout (project-name)"
+category: Workflow
+tags: [workflow, opengoal, scout]
+---
+
+# $CommandPrefix:scout
+
+## Constraints
+
+- (command entry, and again on the first turn after a compaction) => load the `opengoal-flow` skill BEFORE reporting status, and say so in one line. A reference is not a load: its rules (checkpoint triggers, documentation timing, CONTEXT.md self-sync, self-verification) only bind once the skill's content is actually in context.
+<!-- @if subagent -->
+- **Delegate** exploration tasks (e.g., file discovery, keyword search, tracing) to **subagents** — analysis and judgment stay with main. Direct implementation work is limited to one-line fixes, except where `opengoal-subagent` designates work main-only (iterative collaboration, 2nd-iteration rework, evolving design).
+- Report subagent results to the user.
+- (first subagent dispatch of the session, or first dispatch after a compaction) => load the `opengoal-subagent` skill BEFORE dispatching and say so in one line (e.g. "opengoal-subagent loaded — dispatching <task> → <model> (<rationale>)"). A dispatch without this load+announcement is a violation: the skill's dispatch rules (model selection/reporting, prompt requirements, post-verify) only bind once its content is actually in context.
+<!-- @else -->
+- Perform analysis and implementation tasks directly.
+- Report results to the user.
+<!-- @endif -->
+- Report status based solely on docs files read during initialization — this includes the `$DocsDir/suspended/*/GOAL.md` front-matter reads in step 2 below and, when a pointer task needs resolving, listing `$DocsDir/archive/goals/` and reading a matching directory's GOAL.md front-matter (the resolver's `parent:` check) — do not read other files proactively.
+- Keep suggestions to 1-2 lines — follow the user's direction if they want something different.
+- Skip suggestions if the user starts with a specific task instruction.
+- GOAL.md tasks are always the unit of progress — DESIGN.md is a reference document, not a progress tracker.
+- In Discovery Mode: don't rush to formalize — sometimes thinking IS the value.
+- (creating CONTEXT.md) => suggest `/$CommandPrefix:context init` — do not write CONTEXT.md directly.
+- (creating GOAL.md) => suggest `/$CommandPrefix:goal init` — do not write GOAL.md directly.
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+# Session Initialization
+
+1. Read all of these files at once (parallel if supported, sequential otherwise):
+   - `$DocsDir/CONTEXT.md`, `$DocsDir/GOAL.md`, `$DocsDir/DESIGN.md`, `$DocsDir/PLAN.md`, `$DocsDir/ROADMAP.md`, `$DocsDir/CHECKPOINT.md`
+   - A file read error means the file does not exist — mark it as "not present" and move on. **Do NOT retry failed reads.**
+2. Always check for suspended goals by listing `$DocsDir/suspended/` (this can be a separate call only if needed), and read the front-matter of each `$DocsDir/suspended/*/GOAL.md` — the same read `goal.md`'s `resume` candidate list and `subgoal`'s Lineage Validation already perform. This is what surfaces a parked parent or sibling even while a sub-goal is the active GOAL.md.
+3. If no GOAL.md exists, also read `$DocsDir/BACKLOG.md` (skip this read when a GOAL is active).
+4. Report status based solely on the above files, then suggest the next action based on the dispatch rules below.
+   - (the active goal has `parent:`, or a suspended goal's front-matter has `parent:` equal to the active goal's `id`) => report the four kinds `goal.md`'s `subgoal list` uses: **Active scope** (the active goal's `id`, and its `parent:` if present); **Parked sub-goals of this lineage** (children of the active goal, and siblings sharing its `parent:`); **the parent**, shown only when the active goal has `parent:`, together with its return promise — it comes back automatically when this sub-goal completes via `/$CommandPrefix:goal archive`, or immediately via `/$CommandPrefix:goal subgoal pause`; **Unrelated peer goals** (suspended goals outside this lineage).
+   - (no active GOAL.md, a suspended goal carries `parent:`) => group the parked sub-goals under their `parent:` alongside the peer goals, so the lineage is visible before `/$CommandPrefix:goal resume` runs.
+   - (otherwise) => no lineage grouping; report suspended goals per State Dispatch below, unchanged. This suppresses the four-kind presentation only — it never suppresses the goals themselves.
+   - (a `→ subgoal: <slug>` pointer task in GOAL.md resolves to **dangling** per `/$CommandPrefix:goal`'s `### Resolving a Pointer Task's Slug`) => report it as a repairable inconsistency, not an error. Use that resolver; do not match slugs here.
+   - (DESIGN.md's or CHECKPOINT.md's front-matter `goal-id` — or PLAN.md's, when it carries one — differs from GOAL.md's `id`) => report it as a repairable inconsistency: an interrupted `suspend`/`resume`/`archive` move left another goal's document at the canonical path. Report only; do not repair.
+
+## State Dispatch
+
+Three exclusive tiers — no CONTEXT.md and no GOAL.md, CONTEXT.md present without GOAL.md, GOAL.md present. Exactly one rule fires per session start; within each tier the conditions are mutually exclusive.
+
+Tier 1 — no CONTEXT.md and no GOAL.md (an active GOAL.md without CONTEXT.md is unusual but belongs to Tier 3 — work proceeds, and Documentation Timing may suggest `/$CommandPrefix:context init` later):
+
+- (no CONTEXT.md, no GOAL.md, no/minimal code — no source files yet; a README or manifest alone is still minimal) => enter **Discovery Mode**
+- (no CONTEXT.md, no GOAL.md, existing codebase — source files present) => suggest `/$CommandPrefix:context init`
+
+Tier 2 — CONTEXT.md present, no GOAL.md (parked work outranks new work):
+
+- (suspended goals exist) => list suspended goals, suggest `/$CommandPrefix:goal resume`
+- (no suspended goals, BACKLOG.md has open items) => list items as next-goal candidates, suggest `/$CommandPrefix:goal init`
+- (no suspended goals, no open BACKLOG items, ROADMAP.md exists) => suggest picking a milestone from ROADMAP.md and starting with `/$CommandPrefix:goal init`
+- (no suspended goals, no open BACKLOG items, no ROADMAP.md) => suggest `/$CommandPrefix:goal init` or `/$CommandPrefix:roadmap init`
+
+Tier 3 — GOAL.md present. Showing the checkpoint summary is a display action, not a handoff — it never competes with the suggestion:
+
+- (CHECKPOINT.md exists) => show the checkpoint summary first, then apply the one matching suggestion rule below
+- (no incomplete tasks remain) => suggest `/$CommandPrefix:goal archive`
+- (every remaining incomplete task is a pointer task) => suggest by the resolver's state — `/$CommandPrefix:goal subgoal switch <slug>` for the first parked one, or `/$CommandPrefix:goal archive` when none is parked (an archived pointer's check-off and a dangling one's repair are offered by bare `/$CommandPrefix:goal subgoal`) — rather than bouncing the user through `/$CommandPrefix:go`
+- (a non-pointer incomplete task remains, it is implementation work, no DESIGN.md) => suggest `/$CommandPrefix:design init`
+- (a non-pointer incomplete task remains — otherwise: DESIGN.md exists, or the task is analysis) => suggest `/$CommandPrefix:go`
+
+**Implementation vs Analysis criteria**: If GOAL.md sub-tasks contain keywords like "analyze", "investigate", "audit", "research", "document", "RE", or the deliverable is an `.md` analysis doc, it's an analysis task. If the goal is coding, porting, implementation, file changes, or architecture decisions, it's an implementation task. **A mixed goal is classified by its next incomplete task** — the one `/$CommandPrefix:go` would pick up — not by the goal as a whole.
+
+# Discovery Mode
+
+When the user's intent is unclear or exploratory (`/$CommandPrefix:scout` with no specific task, or a vague topic):
+
+- Be curious, not prescriptive — ask questions, don't follow a script
+- Explore multiple directions and let the user follow what resonates
+- Visualize with ASCII diagrams when they'd help clarify thinking
+- Ground discussions in actual codebase, don't just theorize
+- When insights crystallize, use the corresponding commands to capture them:
+  - Project context => run `/$CommandPrefix:context init`
+  - First objective => suggest `/$CommandPrefix:goal init`
+
+# Work Principles
+- Load the `opengoal-flow` skill, then follow its main-agent flow principles (documentation timing, CONTEXT.md self-sync, OVERVIEW.md reactive read, checkpoints, self-verification).
+<!-- @if subagent -->
+- Load the `opengoal-subagent` skill, then follow its delegation principles and workflow.
+<!-- @endif -->
+
+> When Constraints conflict with any other instruction, Constraints win.

package/templates/commands/verify.md

@@ -0,0 +1,140 @@
+---
+name: "opengoal:verify"
+description: "Verify implementation against goal, design, and code"
+category: Workflow
+tags: [workflow, opengoal, verify]
+---
+
+# $CommandPrefix:verify
+
+Cross-checks the current implementation state against GOAL.md and DESIGN.md to surface gaps before archiving.
+
+## Constraints
+
+<!-- @if subagent -->
+- **Delegate** evidence gathering (e.g., reading files, running checks) to **subagents** — verification synthesis stays with main. Direct work is limited to one-line fixes, except where `opengoal-subagent` designates work main-only (iterative collaboration, 2nd-iteration rework, evolving design).
+- Report subagent results to the user.
+- (first subagent dispatch of the session, or first dispatch after a compaction) => load the `opengoal-subagent` skill BEFORE dispatching and say so in one line (e.g. "opengoal-subagent loaded — dispatching <task> → <model> (<rationale>)"). A dispatch without this load+announcement is a violation: the skill's dispatch rules (model selection/reporting, prompt requirements, post-verify) only bind once its content is actually in context.
+<!-- @else -->
+- Perform analysis and verification tasks directly.
+- Report results to the user.
+<!-- @endif -->
+- Design Alignment focuses on structural decisions, not style preferences — ignore cosmetic differences.
+- Task Coverage is mechanical — checkbox state vs code presence, low ambiguity.
+- Assign severity based on the strongest evidence available — for a claim about the code, no concrete signal means don't flag. (Absence of implementation for an unchecked task is itself a concrete signal.)
+- Omit issues without a `file:line` pointer and a concrete action.
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Usage
+
+`/$CommandPrefix:verify [focus area]`
+
+- If `$ARGUMENTS` has content, use it as the focus area for verification.
+- If empty, infer the verification scope from the current session context (recent work, active goal, design).
+
+Verify assumes it runs in the session where the goal progress happened — its checks are grounded in that session's context, not in cross-session state.
+
+# Workflow
+
+## Phase 1 — Read Context
+
+Read `$DocsDir/GOAL.md` and `$DocsDir/DESIGN.md` at once (parallel if supported, sequential otherwise). Skip if already in session context — but re-read if the goal occupying the canonical paths has changed since the last read: a `subgoal` verb, `goal suspend`/`resume`, or `goal archive`'s sub-goal completion all swap the documents at those paths. A file read error means the file does not exist — **do NOT retry failed reads.**
+- If GOAL.md has front-matter `id`, glob `$DocsDir/logs/*-<goal-id>-*.md` and read the latest 1-2 for session history.
+
+### Check Dispatch
+
+The session-context guard precedes the file-presence rules below — when both match, it wins.
+
+- (GOAL.md or DESIGN.md exists, but no goal progress happened in this session, `$ARGUMENTS` empty) => report: "This session carries no verifiable goal context — verify checks the session's progress. Run it in the session where the work happened, or pass a focus area." Then stop.
+- (GOAL + DESIGN) => run full verification (Phases 2–4)
+- (GOAL only) => skip Phase 2, run Phases 3–4
+- (DESIGN only) => skip Phases 3–4, run Phase 2
+- (neither, $ARGUMENTS given) => freeform check against `$ARGUMENTS`
+- (neither, no $ARGUMENTS) => ask the user what to verify
+
+## Phase 2 — Design Alignment
+
+> Requires: DESIGN.md. Skip if absent.
+
+Check whether the implementation follows the planned architecture.
+
+1. Scan DESIGN.md for structural decisions (file layout, module boundaries, execution flow).
+2. Compare each against the actual codebase.
+3. Flag contradictions as **CONFLICT** — "Deviates from design: \<decision\>"
+4. Spot new/modified files that break project conventions.
+5. Flag convention breaks as **STYLE** — "Breaks project pattern: \<details\>"
+
+## Phase 3 — Task Coverage
+
+> Requires: GOAL.md.
+
+Walk every checkbox in GOAL.md (including nested sub-tasks) and classify each — the pointer-task rule precedes the two evidence-based rules, so it wins over them:
+
+- (checked `[x]`) => counted as done — a pointer task included; only `/$CommandPrefix:goal archive`'s sub-goal completion path can have checked one
+- (unchecked pointer task — a `→ subgoal: <slug>` line) => **SUBGOAL** — never **REVIEW**, never **BLOCKED**, whatever the codebase shows; the evidence belongs to that goal, not this one
+- (unchecked `[ ]`, codebase evidence found) => **REVIEW** — likely done but unmarked
+- (unchecked `[ ]`, no codebase evidence) => **BLOCKED** — work remains
+
+For an unchecked pointer task, report where the delegated work stands and never check it off:
+
+Resolve each slug with `/$CommandPrefix:goal`'s `### Resolving a Pointer Task's Slug` — use that resolver, do not match slugs here:
+
+- (parked) => report that sub-goal's own `done / total` from `$DocsDir/suspended/<slug>/GOAL.md`
+- (archived) => report it archived with the pointer left unchecked
+- (dangling) => report it dangling — `/$CommandPrefix:goal subgoal` lists it and explains the repair
+
+Output: `done / total` with list of unmarked, blocked, and **SUBGOAL** items.
+
+## Phase 4 — Intent Match
+
+> Requires: GOAL.md with at least one completed task.
+
+For each completed task, check whether the implementation matches what the task describes:
+
+1. Locate relevant code paths via function names, types, or module structure.
+2. Evaluate whether the code behavior matches the stated goal.
+3. Flag mismatches as **DRIFT** — "Implementation differs from stated intent: \<details\>"
+
+If `$ARGUMENTS` narrows the scope, focus on that area first.
+
+## Phase 5 — Report
+
+```
+## Verify Summary
+
+| Check            | Result                |
+|------------------|-----------------------|
+| Design Alignment | clean / N conflicts   |
+| Task Coverage    | done/total (N issues) |
+| Intent Match     | N drifts found        |
+```
+
+**Issues (ordered by severity):**
+
+- **BLOCKED**: Incomplete work that must be finished
+- **CONFLICT**: Implementation contradicts design decisions
+- **SUBGOAL**: Task delegated to a sub-goal. A **parked** one ranks above everything that permits archiving, because each of those would send the user into `/$CommandPrefix:goal archive`'s refusal; an **archived** or **dangling** one blocks nothing and is reported for repair only
+- **DRIFT**: Completed work that doesn't match stated intent
+- **REVIEW**: Ambiguous situations needing user judgment
+- **STYLE**: Convention deviations worth considering
+
+### Archive Readiness
+
+These verdicts are **advisory by design** — they inform the user's decision at verify time. `/$CommandPrefix:goal archive` reads no verify state and runs whenever its own guards pass; the intended flow is simply to run verify before archiving.
+
+- (highest = BLOCKED or CONFLICT) => do not archive — resolve first
+- (highest = SUBGOAL, at least one parked) => nothing here blocks archiving, but `/$CommandPrefix:goal archive` will refuse while that sub-goal is parked — name the slug and point at `/$CommandPrefix:goal subgoal switch <slug>` to finish it
+- (highest = SUBGOAL, none parked) => it blocks nothing and decides nothing — apply this list to the highest issue below it (clear to archive if none), reporting the archived-or-dangling pointers alongside. A dangling pointer is only repairable while this goal is still active — after archiving, `subgoal init` has no goal to attach to
+- (highest = DRIFT) => archive at your discretion
+- (highest = REVIEW) => surface the REVIEW items and let the user decide before archiving — REVIEW means user judgment is required
+- (highest = STYLE) => archive — cosmetic findings do not block
+- (no issues) => clear to archive
+
+## Work Principles
+
+<!-- @if subagent -->
+- Load the `opengoal-subagent` skill, then follow its delegation principles and workflow.
+<!-- @endif -->
+
+> When Constraints conflict with any other instruction, Constraints win.

package/templates/skills/opengoal-flow/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: opengoal-flow
+description: Main-agent flow principles for opengoal workflows — documentation timing, CONTEXT.md self-sync, checkpoint triggers, OVERVIEW.md reactive read, self-verification, and decision support. Use whenever the main agent is driving an opengoal session, regardless of subagent availability.
+license: MIT
+metadata:
+  version: "1.0"
+  generatedBy: $OpenGoalVersion
+---
+
+# opengoal-flow
+
+## Constraints
+
+- Never execute documentation commands automatically — suggest only.
+- At most one documentation suggestion per turn — when several triggers fire, pick the highest-value one and drop the rest.
+- (a suggestion was made and the user did not act on it) => do not repeat it this session unless the user asks or new evidence changes the case. Silence is an answer. Exception: the single wrap-up `/$CommandPrefix:context sync` suggestion may restate an earlier unacted one — the signals accumulated since ARE the new evidence, and CONTEXT.md Self-Sync's per-session cap governs it.
+- Never auto-read OVERVIEW.md. Only read after a reactive trigger fires AND the user approves — except when a user-invoked command's own procedure reads it (`/$CommandPrefix:overview sync`, or `/$CommandPrefix:recap` routing a project-level finding): that is this Constraint's own named exception, and the invocation is the approval.
+- Self-verification is mandatory before marking any GOAL.md task or ROADMAP.md milestone as done.
+- Handoff recommendations (after any opengoal command or task completes) are single-path and decisive — do not enumerate alternatives. When two next-steps both seem reasonable, pick based on Self-Verification status, GOAL.md priority, and risk profile; do not push the choice to the user. Presenting multiple options applies only to genuine decision forks, not handoffs.
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Command Recognition
+
+Interpret user input as opengoal command execution when intent is clear from context — no explicit `/$CommandPrefix` prefix required.
+
+Execute when any of:
+- **Explicit invocation** (with or without minor deviations): `/$CommandPrefix:goal init`, `/$CommandPrefix goal init`, `/$CommandPrefix:goal init & design init`
+- **Confirmation of pending action**: AI recommended a specific opengoal command in the prior turn, user reply is a brief confirmation ("ok", "yes", "go")
+- **Continuation in active flow**: user names the next opengoal step in ongoing context (e.g., "breakdown now" after goal init)
+- **Task-execution intent**: user expresses task-level intent that maps to an opengoal command (e.g., "proceed with task N" → `/$CommandPrefix:go`, "save progress" → `/$CommandPrefix:goal checkpoint`, "archive this goal" → `/$CommandPrefix:goal archive`)
+
+> Destructive operations (overwriting existing files, archive) still follow state-aware prompts — in-context confirmation does not bypass those guards.
+
+## Documentation Timing
+
+- (implementation plan crystallizes — files, design decisions, execution order) => suggest `/$CommandPrefix:design init`
+- (design changes during implementation) => suggest `/$CommandPrefix:design sync` if `$DocsDir/DESIGN.md` exists, else `/$CommandPrefix:design init`
+- (the user articulates a new project principle) => CONTEXT.md Self-Sync owns this trigger — apply its rule there, which also handles the no-CONTEXT.md case. Resource and workflow-step changes are not suggestion triggers either; they accumulate silently under Self-Sync too
+- (multiple GOALs need a higher-level plan) => suggest `/$CommandPrefix:roadmap init`
+- (new milestone identified) => suggest `/$CommandPrefix:roadmap add` if `$DocsDir/ROADMAP.md` exists, else `/$CommandPrefix:roadmap init`
+- (DESIGN.md step completed) => suggest `/$CommandPrefix:design sync`
+- (multiple design decisions or context changes accumulated but not yet documented) => suggest `/$CommandPrefix:recap`
+
+Keep suggestions brief and declarative — a statement, not a question: "Implementation plan ready — `/$CommandPrefix:design init` documents it." A suggestion phrased as a question demands a reply; a statement can be passed over without friction.
+
+## CONTEXT.md Self-Sync
+
+CONTEXT.md is the main agent's working memory — it should grow as the session reveals new project facts. Accumulate these signals silently; do NOT suggest on each one:
+
+- new resource worth referencing (file, directory, external system)
+- workflow step refined — a procedure the AI repeats and should remember
+- new analysis topic / index entry — for projects that maintain analysis tables
+
+Then:
+
+- (user articulates a new project principle — e.g. "always do X", "never do Y") => suggest `/$CommandPrefix:context sync` now if `$DocsDir/CONTEXT.md` exists, else `/$CommandPrefix:context init`; an explicit user rule is worth interrupting for. This is the single home of the principle trigger — Documentation Timing defers here
+- (session ending, or several signals accumulated) => suggest `/$CommandPrefix:context sync` once as part of wrap-up. Wrap-up tiebreak with Checkpoint Triggers under the one-suggestion cap: incomplete GOAL.md tasks remain => the checkpoint suggestion wins (work-loss protection first); otherwise this one
+
+Cap: at most two `/$CommandPrefix:context sync` suggestions per session — one for an explicit principle, one at wrap-up.
+
+## OVERVIEW.md Reactive Read
+
+OVERVIEW.md is a project-level architectural reference. It is **never auto-loaded**. Read it only when a reactive event explicitly signals that big-picture context is missing — or when a user-invoked command's own procedure reads it (the exemption bullet below, which needs no approval step):
+
+- (GOAL intent appears to conflict with the actual code structure) => check for OVERVIEW.md, ask user before reading
+- (a subagent reports "project-wide context needed" or paraphrases architecture inaccurately) => same
+- (user prompt literally asks "why was X designed this way?", "what's the overall structure?", "big picture", or types `$DocsDir/OVERVIEW.md`) => same
+- (the user invoked a command whose own procedure reads OVERVIEW.md — `/$CommandPrefix:overview sync`, or `/$CommandPrefix:recap` routing a project-level finding) => not an auto-read; the invocation itself is the approval, proceed without the affordance step
+- (otherwise) => do NOT read OVERVIEW.md, do NOT suggest reading
+
+When a reactive trigger fires (the user-invoked-procedure exemption skips this — the invocation is the approval, so steps 3-4 do not apply to it):
+1. Confirm `$DocsDir/OVERVIEW.md` exists (existence check only).
+2. If absent, inform the user and proceed without it.
+3. If present, surface the affordance to the user — *do not auto-read*. Example: "Architectural ambiguity detected. `$DocsDir/OVERVIEW.md` is available — load it?"
+4. Read only after explicit user approval, then keep the result in session (skip-if-loaded for subsequent triggers).
+
+> Bias control: when the trigger condition is uncertain, **default to NOT reading**. The cost of missing one read is small; the cost of always-loading is structural.
+
+## Checkpoint Triggers
+
+A checkpoint exists to survive context loss (compaction) *mid-goal*. Only two things justify suggesting one:
+
+- (platform surfaces a compaction-imminent / auto-compact / context-limit notice, or exposes actual context-usage figures nearing the limit — e.g. an injected system warning) => suggest `/$CommandPrefix:goal checkpoint` NOW. This is the only reliable context-pressure signal. Never estimate your own context % or infer pressure from how long the session "feels" — that estimate tracks turn count, not tokens, and misfires early.
+- (user explicitly asks to save/pause, or is ending the session) => suggest `/$CommandPrefix:goal checkpoint`.
+
+On platforms that inject no warning, the second trigger is the only one — this is intentional: GOAL.md checkboxes and docs/logs already persist state as work completes, so a missed checkpoint is cheap.
+
+> Do NOT suggest a checkpoint on task count, milestone/goal completion, or a sense that the session has "grown long." At goal completion the right move is `/$CommandPrefix:goal archive`, not a checkpoint. When in doubt, stay silent.
+
+## Blocker Handling
+
+When the current goal cannot proceed (discovered bug, missing dependency, blocking issue):
+
+- (blocker identified, active goal has `parent:`, the parent is parked under `$DocsDir/suspended/`) => suggest `/$CommandPrefix:goal subgoal pause` first to return to the parent, then follow the ordinary blocker path there — `/$CommandPrefix:goal suspend` and `/$CommandPrefix:goal init` are both refused while a sub-goal is active
+- (blocker identified, active goal has `parent:`, the parent is missing from `$DocsDir/suspended/`) => `subgoal pause` will refuse too; suggest finishing or archiving the sub-goal (`/$CommandPrefix:goal archive` handles the missing parent and leaves the slot empty), then starting the blocker goal with `/$CommandPrefix:goal init`
+- (blocker identified, current GOAL cannot progress, no `parent:`) => suggest `/$CommandPrefix:goal suspend` followed by `/$CommandPrefix:goal init "<blocker description>"` to address the blocker as its own goal
+- (blocker goal archived, suspended goals remain) => suggest `/$CommandPrefix:goal resume` to continue a suspended goal
+- (nested blockers) => same pattern recursively; `suspended/<goal-id>/` stacks naturally, `resume` presents a list when multiple
+
+This preserves "one active GOAL.md at a time" — simpler than in-place stacking schemes.
+
+## Sub-goal Handling
+
+Blocker, sub-goal, and backlog partition one space between them. Route a discovery on this discriminant, not on how urgent it feels:
+
+- (goal cannot progress until this is fixed) => Blocker Handling above
+- (goal can still progress, this serves the goal, needed now, larger than a task) => sub-goal — suggest `/$CommandPrefix:goal subgoal init "<description>"`
+- (goal can still progress, not needed now) => Backlog Handling below
+- (goal can still progress, this serves the goal, needed now, fits in a task) => ordinary task — just do it, no ceremony
+
+All four conditions of the sub-goal branch are load-bearing. Drop "this serves the goal" and out-of-scope urgent work routes into a sub-goal — which is exactly what `$DocsDir/BACKLOG.md` exists to prevent. Drop "larger than a task" and ordinary work turns into a goal.
+
+A sub-goal is an ordinary goal carrying `parent: <parent-id>` in its front-matter — no new document type, no new location. Shape of the lifecycle: `/$CommandPrefix:goal subgoal init` parks the parent and starts it; it then owns its own `$DocsDir/DESIGN.md` / `PLAN.md` / `CHECKPOINT.md` like any goal and the ordinary Documentation Timing and Execution Handoff rules apply unchanged; `/$CommandPrefix:goal subgoal pause` parks it and returns to the parent; `/$CommandPrefix:goal subgoal switch <slug>` moves between parked ones in the active goal's lineage; bare `/$CommandPrefix:goal subgoal` lists them. Completion is `/$CommandPrefix:goal archive`, which returns to the parent automatically. `/$CommandPrefix:goal` owns every one of those procedures — the slugs, the pointer task, the guards — so point at the verb rather than describing what it does.
+
+The intent is what matters — park the parent, create a linked goal that records its parent, return to the parent when it is done — so where `/$CommandPrefix:goal subgoal` is unavailable, achieve the same shape manually by suspending the parent and creating a goal whose front-matter records its parent.
+
+### "Pause" Precedence
+
+A bare "pause" now has three readings: stop working (the `/$CommandPrefix:go` loop exit), save state (`/$CommandPrefix:goal checkpoint`), and park this sub-goal (`/$CommandPrefix:goal subgoal pause`). Resolve the word first, then apply the matching section:
+
+- (no sub-goal active) => stop working; Checkpoint Triggers decides whether to also suggest `/$CommandPrefix:goal checkpoint`
+- (sub-goal active, user names the sub-goal or asks to get back to the parent) => `/$CommandPrefix:goal subgoal pause`
+- (sub-goal active, user names saving / context / ending the session) => Checkpoint Triggers, unchanged
+- (sub-goal active, nothing in the phrasing picks a reading) => ask which of the three is meant
+
+> Asking here does not violate the Constraint that handoff recommendations are single-path and never a menu — that Constraint's own final sentence exempts genuine decision forks, and this is one, not a handoff. The three readings leave the session in different states, and guessing wrong parks a goal the user wanted left active.
+
+## Backlog Handling
+
+When a discovery falls outside the current goal's scope but does not block it (unrelated bug, improvement idea, tech debt):
+
+- (out-of-scope discovery, current GOAL can still progress) => offer to append a one-line entry to `$DocsDir/BACKLOG.md`, then continue the current task
+- (diagnosis is substantial) => record it in `$DocsDir/logs/` or `discussion/`; the backlog entry keeps only the one-liner + a pointer
+- Entry format: `- [ ] YYYY-MM-DD <one-liner> (found during <goal-id>)`
+
+Blocking discoveries belong to Blocker Handling (suspend); non-blocking ones split between Sub-goal Handling and here — run them through that section's discriminant, never default them into the backlog.
+
+## Self-Verification
+
+Before checking off a GOAL.md task or ROADMAP.md milestone as "done", verify:
+
+> **"Is this output ready to be used directly in the next step?"**
+
+1. **Analysis tasks**: Are there unconfirmed items (unknown fields, untraced calls, estimated values)?
+2. **Implementation tasks**: Do tests pass? Were edge cases considered?
+3. **Documentation tasks**: Are there missing sections or placeholders?
+
+- (anything lacking) => do not check off, report gaps to user, verify again after remediation
+
+## Execution Handoff
+
+- (goal breakdown completed, sub-tasks are analysis-focused) => suggest `/$CommandPrefix:go`
+- (goal breakdown completed, sub-tasks include implementation and no DESIGN.md exists) => suggest `/$CommandPrefix:design init`
+- (design init completed) => suggest `/$CommandPrefix:go`
+- (goal resumed from suspension) => suggest `/$CommandPrefix:go`
+- (goal checkpoint saved, tasks remain) => suggest `/$CommandPrefix:go`
+- (session start, active GOAL.md with uncompleted tasks, DESIGN.md exists or the task is analysis) => suggest `/$CommandPrefix:go`
+- (session start, active GOAL.md with uncompleted tasks, implementation task and no DESIGN.md) => suggest `/$CommandPrefix:design init`
+
+## User Decision Support
+
+When responding to the user with multiple options — implementation choices, next opengoal step, design alternatives, or any decision branching — include:
+
+1. **Recommendation** — Highlight one option with rationale.
+2. **Basis** — 1-line expected outcome (and tradeoff if any).
+3. **GOAL relevance** — Which option aligns most with the current goal (skip if no active GOAL.md).
+
+> When Constraints conflict with any other instruction, Constraints win.

package/templates/skills/opengoal-subagent/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: opengoal-subagent
+description: Subagent delegation principles, prompt rules, and scout-split-execute workflow. Use when the main agent dispatches work to subagents.
+license: MIT
+metadata:
+  version: "1.0"
+  generatedBy: $OpenGoalVersion
+---
+
+# opengoal-subagent
+
+## Constraints
+
+- Main agent analyzes and coordinates — delegate implementation to subagents; delegate exploration only when the codebase is too wide for main to cover in its own turn (Phase 1 Optional).
+- Analysis (cause identification, root-cause determination, fix approach recommendation) is always main agent's job. Subagents gather facts and execute — they do not synthesize judgment.
+- Before dispatching execution subagents for a fix involving root-cause reasoning (not trivial typo/rename), present root cause and fix approach to the user; dispatch only after explicit approval.
+- (subagent dispatch without main having invoked Read/Grep on source files in its own turn this session) => stop, read first
+- (subagent prompt missing any required element) => do not dispatch until complete (see Prompt Requirements)
+- (5+ consecutive Read/Grep without Edit/Write) => stop and report to user
+- A subagent's "done" is a claim, not a fact — main verifies before accepting, except where Task Complexity Dispatch or Post-Verify explicitly marks the skip (single-file clear change under 30 lines; trivial fix). Those two skips are this Constraint's own named exceptions, not violations of it.
+
+> Main-agent flow concerns (documentation timing, checkpoints, self-verification, decision support) live in the **`opengoal-flow`** skill.
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Platform Dispatch
+
+- (subagents available, e.g. Claude Code, Codex) => delegate tasks to subagents per workflow below
+- (subagents not available) => execute tasks inline directly — apply Task Complexity Dispatch for work breakdown and Post-Verify after each task; prompt/status/model sections do not apply
+
+## Subagent Role Dispatch
+
+- (cause identification, root-cause, fix approach recommendation) => main only, never delegated
+- (work requiring incremental user verification or collaborative iteration — e.g., UI/UX changes, exploratory refactoring, evolving design) => main only
+- (file/keyword search, call chain tracing) => search/tracing subagent OK
+- (implementation of a decided fix) => execute subagent OK
+
+Scout subagents gather facts. They do not state causes or recommend fixes.
+
+## Task Complexity Dispatch
+
+- (1-line fix, typo) => main agent fixes directly
+- (single file, clear change, < 30 lines) => one subagent, skip post-verify
+- (multi-file or design judgment needed, scout not done) => main reads source and analyzes first
+- (multi-file or design judgment needed, scout done) => dispatch subagents for split execution
+- (2nd iteration on same work area after a subagent fix) => main agent executes inline — subagents lack stop/resume; iterative collaboration needs inline turns
+- (user indicates need for inline collaboration) => main agent executes inline
+- (otherwise) => ask user for scope guidance
+
+## Subagent Prompt Requirements
+
+Each subagent prompt must include all seven elements:
+
+1. **Scope** — Explicitly bound files/modules.
+2. **Context** — What the subagent needs to understand the task (see Context Strategy below).
+3. **Goal** — Specific completion criteria (e.g., "tests pass", "parser implemented with output").
+4. **Constraints** — What must not be modified.
+5. **Output** — Expected format (e.g., "change summary + findings").
+6. **Depth** — Analysis depth (e.g., "call chain 2 levels deep", "direct dependencies only").
+7. **Ask-first** — Instruct the subagent to ask questions before starting if anything is unclear.
+
+### Context Strategy
+
+Main reads and selects — the subagent focuses on execution.
+
+- (implementation) => include source of files to be modified; reference-only files as paths
+- (exploration/analysis) => specify target paths and search scope (no source embedding)
+
+### Prompt Example
+
+```
+Scope: src/auth/session.ts only. Do not modify other files.
+
+Context:
+Current implementation of src/auth/session.ts:
+[paste full source here]
+
+Goal: Replace JWT verification with session-based auth. Existing tests must pass.
+Constraints: Use express-session API only. No custom middleware.
+Output: Change summary + test results.
+Depth: session.ts internals only. No call chain tracing needed.
+Ask-first: If anything is unclear, ask before starting.
+```
+
+## Model Selection
+
+Selecting a tier is part of dispatch — inherit is a fallback, not a default.
+
+- (single file, clear spec) => fast model (e.g. haiku)
+- (multi-file, integration/judgment) => standard model (e.g. sonnet)
+- (architecture, design, review) => capable model (e.g. opus)
+- (otherwise) => standard model
+
+Know what "inherit" resolves to before choosing it: if the platform declares the session model (e.g. in the system prompt), factor it in — on a premium-tier session, inheriting is the most expensive possible dispatch, and a lower tier per the table is usually sufficient. Inherit ONLY when: (a) the platform cannot specify a model, (b) the session model is unknown, or (c) the task genuinely needs the session-tier model — and name which case applies in the dispatch report.
+
+When dispatching, tell the user which model was requested and why, in one phrase — e.g. "execute subagent → haiku (single-file mechanical edit)". Report the *requested* model only — platforms may override silently.
+
+Placement matters as much as content: put the dispatch report in the turn's **final message**, not only as interim text between tool calls — on some platforms interim text is not reliably shown, so a report the user never sees is a violation even though it was written. The same applies to the skill-load announcement.
+
+- (dispatched without specifying despite the rules above) => still report honestly: "inherited (session default)" — never guess what ran
+- (platform exposes no model choice) => skip selection, note "platform default"
+
+## Workflow: Scout → Split → Execute
+
+### Phase 1 — Scout
+
+#### Required (main only)
+1. Identify candidate files (keyword search, trace from entry point).
+2. Read candidate files in parallel — invoke Read/Grep in main's own turn, not receiving summaries from a subagent.
+3. Identify cause and define scope.
+
+#### Optional (subagent, only if main's scope insufficient)
+- (codebase too wide for main to cover in this turn) => dispatch search/tracing subagent with explicit paths from step 1
+- (main answered its questions) => skip, proceed to Phase 2
+
+### Phase 2 — Split
+
+- (PLAN.md exists) => use PLAN.md tasks as the split basis
+- (PLAN.md absent, DESIGN.md exists) => use DESIGN.md Execution Order as the split basis
+- (neither) => derive split from scout findings
+
+Judge existence at the canonical path now, not from session memory — any goal swap (a `subgoal` verb, `goal suspend`/`resume`, or `goal archive`'s sub-goal completion) may have replaced both documents since they were last read.
+
+1. Break work into independent sub-tasks.
+2. Apply split criteria: different files/modules, no shared state.
+3. Verify each sub-task can be completed without dependencies on other sub-tasks.
+
+### Phase 3 — Execute (Parallel)
+
+for each task:
+  1. Construct subagent prompt with all seven required elements.
+     - If PLAN.md was read earlier, include the corresponding task section as additional Context — but re-read it first if the goal occupying the canonical paths has changed since (a `subgoal` verb, `goal suspend`/`resume`, or `goal archive`'s sub-goal completion). A cached PLAN.md can belong to a different goal than the one being worked.
+  2. Dispatch subagent.
+  3. Handle status response (see Status Protocol below).
+  4. Post-verify: main confirms the output (see Post-Verify below).
+  5. Report result to user.
+
+After all tasks complete: consolidate results, check for conflicts, and report to user.
+
+#### Status Protocol
+
+loop until resolved:
+  - (DONE) => post-verify, then mark complete
+  - (DONE_WITH_CONCERNS, correctness/scope issue) => resolve before proceeding
+  - (DONE_WITH_CONCERNS, observation) => note it, proceed to post-verify
+  - (NEEDS_CLARIFICATION) => answer the subagent's questions, re-dispatch with answers
+  - (NEEDS_CONTEXT) => provide missing context, re-dispatch
+  - (BLOCKED) => break task down further or escalate to user
+
+#### Post-Verify
+
+Main agent confirms subagent output before marking a task complete:
+
+- (implementation task) => read changed files, compare against GOAL.md task description
+- (exploration/analysis task) => spot-check 1-2 key claims against the codebase
+- (subagent returned unrequested analysis — cause, recommendation, judgment) => main re-does the analysis from source; subagent's synthesis is advisory only
+- (trivial fix) => skip — the skip exempts only the change itself; the unrequested-analysis rule above still applies to anything the subagent volunteered
+
+> When Constraints conflict with any other instruction, Constraints win.