@opellen/opengoal 1.0.0

package/dist/templates.d.ts

@@ -0,0 +1,20 @@
+import { type PlatformAdapter, type CommandMeta } from "./platforms/index.js";
+export declare const DEFAULT_PREFIX = "opgl";
+export interface OpenGoalConfig {
+    tools: string[];
+    subagent: boolean;
+    root: string;
+    docsDir: string;
+    codebaseDir: string;
+    prefix: string;
+    force?: boolean;
+}
+export interface TemplateEntry {
+    src: string;
+    dst: string;
+    adapter: PlatformAdapter;
+    meta: CommandMeta;
+    rawContent: string;
+}
+export declare function resolveTemplates(config: OpenGoalConfig): TemplateEntry[];
+export declare function renderFile(entry: TemplateEntry, config: OpenGoalConfig): string;

package/dist/templates.js

@@ -0,0 +1,98 @@
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { renderTemplate } from "./marker.js";
+import { getAdapters } from "./platforms/index.js";
+import { skillInstallPath, formatSkill } from "./skills/generate.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = join(__dirname, "..", "templates");
+// Installed CLI version — injected into skill metadata.generatedBy.
+// Read once at module load from the shipped package.json.
+const OPENGOAL_VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+        return String(pkg.version ?? "0.0.0");
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+export const DEFAULT_PREFIX = "opgl";
+const COMMAND_TEMPLATES = [
+    "scout", "goal", "context", "design",
+    "roadmap", "verify", "recap", "overview", "go",
+];
+const SKILL_TEMPLATES = [
+    { src: "skills/opengoal-subagent/SKILL.md", skillName: "opengoal-subagent" },
+    { src: "skills/opengoal-flow/SKILL.md", skillName: "opengoal-flow" },
+];
+function parseMeta(content) {
+    const normalized = content.replace(/\r\n/g, "\n");
+    const fmMatch = normalized.match(/^---\n([\s\S]*?)\n---/);
+    if (!fmMatch)
+        return { name: "", description: "" };
+    const fm = fmMatch[1];
+    const nameMatch = fm.match(/name:\s*"?(?:[\w-]+:)?([\w-]+)"?/);
+    const descMatch = fm.match(/description:\s*"([^"]+)"/);
+    const categoryMatch = fm.match(/category:\s*(\S+)/);
+    const tagsMatch = fm.match(/tags:\s*\[([^\]]*)\]/);
+    const tags = tagsMatch
+        ? tagsMatch[1]
+            .split(",")
+            .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+            .filter(Boolean)
+        : undefined;
+    return {
+        name: nameMatch?.[1] ?? "",
+        description: descMatch?.[1] ?? "",
+        category: categoryMatch?.[1],
+        tags,
+    };
+}
+export function resolveTemplates(config) {
+    const adapters = getAdapters(config.tools);
+    const entries = [];
+    const commandMetas = COMMAND_TEMPLATES.map((cmd) => {
+        const src = `commands/${cmd}.md`;
+        const rawContent = readFileSync(join(TEMPLATE_DIR, src), "utf-8");
+        return { cmd, src, rawContent, meta: parseMeta(rawContent) };
+    });
+    const skillContents = SKILL_TEMPLATES.map((skill) => ({
+        ...skill,
+        rawContent: readFileSync(join(TEMPLATE_DIR, skill.src), "utf-8"),
+    }));
+    for (const adapter of adapters) {
+        if (adapter.supportsCommands !== false) {
+            for (const { cmd, src, rawContent, meta } of commandMetas) {
+                entries.push({ src, dst: adapter.commandPath(cmd, config.prefix), adapter, meta, rawContent });
+            }
+        }
+        for (const skill of skillContents) {
+            entries.push({
+                src: skill.src,
+                dst: skillInstallPath(adapter, skill.skillName),
+                adapter,
+                meta: { name: skill.skillName, description: "" },
+                rawContent: skill.rawContent,
+            });
+        }
+    }
+    return entries;
+}
+export function renderFile(entry, config) {
+    const content = entry.rawContent.replace(/\r\n/g, "\n");
+    const rendered = renderTemplate(content, {
+        conditions: {
+            subagent: config.subagent,
+        },
+    });
+    const substituted = rendered
+        .replace(/\$DocsDir/g, config.docsDir)
+        .replace(/\$CodebaseDir/g, config.codebaseDir)
+        .replace(/\$OpenGoalVersion/g, OPENGOAL_VERSION)
+        .replace(/\$CommandPrefix/g, config.prefix);
+    if (entry.src.startsWith("skills/")) {
+        return formatSkill(substituted);
+    }
+    return entry.adapter.formatCommand(substituted, entry.meta, config.prefix);
+}

package/dist/ui/ascii-logo.d.ts

@@ -0,0 +1,6 @@
+export declare const OPENGOAL_LOGO: {
+    readonly frame: readonly ["  ▄▄▄▄▄▄▄▄▄▄▄▄  ", " ██          ██ ", " ██          ██ ", " ██             ", " ██             ", " ██             ", " ██          ██ ", " ██          ██ ", "  ▀▀▀▀▀▀▀▀▀▀▀▀  "];
+    readonly inner: readonly ["                ", "                ", "                ", "     ░▒▒▒▒░     ", "     ▒▒██▒▒     ", "     ░▒▒▒▒░     ", "                ", "                ", "                "];
+};
+export declare const OPENGOAL_LOGO_WIDTH: number;
+export declare const OPENGOAL_LOGO_HEIGHT: 9;

package/dist/ui/ascii-logo.js

@@ -0,0 +1,45 @@
+// The OpenGoal mark in text: an open frame with the current goal inside it.
+//
+// Two-layer logo. Layers are overlaid at render time: any non-space char in
+// `inner` wins over `frame`. This lets the same block char carry a different
+// color depending on which layer it belongs to, without a parallel mask array
+// to keep in sync — `frame` renders in the muted structural tone, `inner` in
+// goal orange (§50: structure stays quiet, the present gets the color).
+//
+// Palette: █ (full), ▓ (dark), ▒ (medium), ░ (light) — shade blocks give a
+// pseudo-anti-aliased gradient that renders uniformly across monospace fonts.
+// The focus point is a blob shaded radially in four rings — █ core, ▓, ▒,
+// then ░ at the corners. All three rows share one width: the cross-arm
+// illusion comes from rows of different lengths, not from dark centres, so
+// equal widths allow a real ring gradient. Density under a single orange.
+//
+// Geometry: 16x9 cells (a terminal cell is roughly twice as tall as it is
+// wide, so the frame reads near-square). The right side stays open across
+// 3 of 9 rows; the top and bottom bars are half-blocks (▄/▀) inset by one
+// column, which both thickens the stroke and stair-steps the corners.
+export const OPENGOAL_LOGO = {
+    frame: [
+        "  ▄▄▄▄▄▄▄▄▄▄▄▄  ",
+        " ██          ██ ",
+        " ██          ██ ",
+        " ██             ",
+        " ██             ",
+        " ██             ",
+        " ██          ██ ",
+        " ██          ██ ",
+        "  ▀▀▀▀▀▀▀▀▀▀▀▀  ",
+    ],
+    inner: [
+        "                ",
+        "                ",
+        "                ",
+        "     ░▒▒▒▒░     ",
+        "     ▒▒██▒▒     ",
+        "     ░▒▒▒▒░     ",
+        "                ",
+        "                ",
+        "                ",
+    ],
+};
+export const OPENGOAL_LOGO_WIDTH = OPENGOAL_LOGO.frame[0].length;
+export const OPENGOAL_LOGO_HEIGHT = OPENGOAL_LOGO.frame.length;

package/dist/ui/colors.d.ts

@@ -0,0 +1,6 @@
+/** --og-ink-muted — the open frame, and anything structural. */
+export declare const structure: import("chalk").ChalkInstance;
+/** --og-goal — the current goal, and the one action worth taking now (§13). */
+export declare const goal: import("chalk").ChalkInstance;
+/** Terminal foreground, so the wordmark is legible on any background. */
+export declare const title: import("chalk").ChalkInstance;

package/dist/ui/colors.js

@@ -0,0 +1,17 @@
+import chalk from "chalk";
+// Palette tokens from docs/design/visual-design-guide.md §11.
+//
+// A terminal's background is unknown at runtime, so the guide's --og-ink
+// (#20211F) and --og-canvas (#F7F6F2) cannot be used directly — either one
+// disappears against half the terminals in use. The frame therefore takes
+// --og-ink-muted, the one neutral that holds contrast on light and dark
+// surfaces alike, and the title falls back to the terminal's own foreground.
+//
+// This preserves the rule that matters (§50): structure stays quiet, the
+// present gets the color.
+/** --og-ink-muted — the open frame, and anything structural. */
+export const structure = chalk.hex("#6B6B66");
+/** --og-goal — the current goal, and the one action worth taking now (§13). */
+export const goal = chalk.hex("#F45A3A");
+/** Terminal foreground, so the wordmark is legible on any background. */
+export const title = chalk.bold;

package/dist/ui/welcome.d.ts

@@ -0,0 +1 @@
+export declare function showWelcome(): Promise<void>;

package/dist/ui/welcome.js

@@ -0,0 +1,77 @@
+import chalk from "chalk";
+import { OPENGOAL_LOGO, OPENGOAL_LOGO_HEIGHT, OPENGOAL_LOGO_WIDTH } from "./ascii-logo.js";
+import { t } from "../i18n/index.js";
+import { structure, goal, title } from "./colors.js";
+export async function showWelcome() {
+    if (!process.stdin.isTTY)
+        return;
+    const cols = process.stdout.columns ?? 80;
+    const compact = cols < 60;
+    const lines = buildScreen(compact);
+    process.stdout.write("\n" + lines.join("\n") + "\n\n");
+    await waitForEnter();
+}
+function buildScreen(compact) {
+    const rightLines = [
+        title("OpenGoal"),
+        chalk.dim(t("welcome.tagline")),
+        "",
+        chalk.dim(t("welcome.setsUp")),
+        "  " + chalk.dim("•") + " " + t("welcome.skills"),
+        "  " + chalk.dim("•") + " " + t("welcome.commands"),
+        "",
+        goal(t("welcome.pressEnter")),
+    ];
+    if (compact) {
+        return rightLines;
+    }
+    const gap = "    ";
+    const totalRows = Math.max(OPENGOAL_LOGO_HEIGHT, rightLines.length);
+    const result = [];
+    for (let i = 0; i < totalRows; i++) {
+        const logo = i < OPENGOAL_LOGO_HEIGHT ? colorLogoRow(i) : " ".repeat(OPENGOAL_LOGO_WIDTH);
+        const text = i < rightLines.length ? rightLines[i] : "";
+        result.push(logo + gap + text);
+    }
+    return result;
+}
+function colorLogoRow(row) {
+    const frame = OPENGOAL_LOGO.frame[row];
+    const inner = OPENGOAL_LOGO.inner[row];
+    let result = "";
+    for (let j = 0; j < OPENGOAL_LOGO_WIDTH; j++) {
+        const innerCh = inner[j];
+        if (innerCh !== " ") {
+            result += goal(innerCh);
+            continue;
+        }
+        const frameCh = frame[j];
+        result += frameCh === " " ? " " : structure(frameCh);
+    }
+    return result;
+}
+function waitForEnter() {
+    return new Promise((resolve) => {
+        const { stdin } = process;
+        const wasRaw = stdin.isRaw ?? false;
+        stdin.setRawMode(true);
+        stdin.resume();
+        const onData = (buf) => {
+            const key = buf[0];
+            if (key === 0x0d || key === 0x0a) {
+                cleanup();
+                resolve();
+            }
+            else if (key === 0x03) {
+                cleanup();
+                process.exit(0);
+            }
+        };
+        const cleanup = () => {
+            stdin.removeListener("data", onData);
+            stdin.setRawMode(wasRaw);
+            stdin.pause();
+        };
+        stdin.on("data", onData);
+    });
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@opellen/opengoal",
+  "version": "1.0.0",
+  "description": "Goal-centric AI harness. Open structure, clear present.",
+  "type": "module",
+  "license": "MIT",
+  "author": "San",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opellen/opengoal.git"
+  },
+  "homepage": "https://github.com/opellen/opengoal#readme",
+  "bugs": {
+    "url": "https://github.com/opellen/opengoal/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "ai",
+    "project-management",
+    "markdown",
+    "context-management"
+  ],
+  "bin": {
+    "opengoal": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./marker": "./dist/marker.js"
+  },
+  "files": [
+    "dist",
+    "templates/commands",
+    "templates/skills"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.0"
+  },
+  "dependencies": {
+    "@inquirer/core": "^11.1.7",
+    "@inquirer/prompts": "^8.3.2",
+    "chalk": "^5.6.2",
+    "yaml": "^2.8.3"
+  }
+}

package/templates/commands/context.md

@@ -0,0 +1,92 @@
+---
+name: "opengoal:context"
+description: "Project context (CONTEXT.md) management (init|sync)"
+category: Workflow
+tags: [workflow, opengoal, context]
+---
+
+# $CommandPrefix:context
+
+Manages `$DocsDir/CONTEXT.md`. Records the **current working context** of the project.
+
+> CONTEXT.md is not a project overview or summary.
+> It captures what is being worked on now, which resources are referenced, and what principles/workflows apply — **context the AI needs immediately at session start**.
+
+## Constraints
+
+- Never overwrite CONTEXT.md without user confirmation.
+- Target ~100 lines or less — this file is read at every session start.
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Usage
+
+`/$CommandPrefix:context <subcommand> [content]`
+
+## Subcommand Dispatch
+
+- (no subcommand given, `$DocsDir/CONTEXT.md` absent) => run init
+- (no subcommand given, `$DocsDir/CONTEXT.md` exists) => run sync
+- (args = init) => see Subcommands: init
+- (args = sync) => see Subcommands: sync
+
+# Subcommands
+
+## init
+
+Creates `$DocsDir/CONTEXT.md`.
+
+1. If CONTEXT.md already exists, notify and confirm overwrite.
+2. If `$ARGUMENTS` has content, incorporate it.
+3. Write project-specific context based on the current session discussion.
+4. Use the skeleton below as a baseline, extending with project-specific sections.
+5. Report: `"Created [CONTEXT.md]($DocsDir/CONTEXT.md)."`
+
+**Skeleton:**
+
+```markdown
+# Project Brief
+- <1-2 lines: what this project is and who it's for>
+- <1-2 lines: core architecture or stack>
+- For deeper architecture/decisions, see `$DocsDir/OVERVIEW.md` (if present).
+
+# Goal Hierarchy
+- If `$DocsDir/ROADMAP.md` exists, it contains the milestone plan.
+  - Mark ROADMAP.md milestones as `done` when completed.
+  - GOAL.md objectives are sub-units of ROADMAP.md milestones — except sub-goals (`parent:` set), which sit below that granularity.
+
+# Current Objective
+- If `$DocsDir/GOAL.md` exists, treat it as the top priority.
+
+# Principles
+
+# Workflow
+- Tasks live in `$DocsDir/GOAL.md` `## Tasks`. Front-matter requires an `id` (slug format).
+- Implementation happens in `$CodebaseDir`.
+- Session progress: `/$CommandPrefix:goal checkpoint` → `$DocsDir/CHECKPOINT.md` (overwritten per session).
+- Deferred discoveries: out-of-scope findings go to `$DocsDir/BACKLOG.md` (persistent parking lot).
+- Work larger than a task, subordinate to the current goal, needed now, and not blocking it: `/$CommandPrefix:goal subgoal init` (the parent resumes automatically on completion; a *blocking* discovery is a blocker, not a sub-goal).
+```
+
+**Project-specific sections** — extend the skeleton with sections appropriate to the project:
+
+- **Resources**: Key file/directory paths and their descriptions
+- **Process**: Project-specific procedures (e.g., porting rules, analysis doc management)
+- **Index/Tables**: Frequently referenced item lists (e.g., analysis topics, API endpoints)
+- **Extended Principles**: Project-specific principles (e.g., 1:1 logic preservation, no magic numbers)
+
+## sync
+
+Reviews current CONTEXT.md and **proposes updates**.
+
+1. Read `$DocsDir/CONTEXT.md`. If absent, suggest init.
+2. If `$ARGUMENTS` has content, use it as update direction.
+3. Identify changes from the current session discussion that should be reflected.
+4. Present changes in **diff format**:
+   - Content to add
+   - Content to modify
+   - Outdated content to remove/update
+5. Apply the changes.
+6. Report: `"Updated [CONTEXT.md]($DocsDir/CONTEXT.md)."`
+
+> When Constraints conflict with any other instruction, Constraints win.

package/templates/commands/design.md

@@ -0,0 +1,113 @@
+---
+name: "opengoal:design"
+description: "Implementation design (DESIGN.md) management (init|sync|archive)"
+category: Workflow
+tags: [workflow, opengoal, design]
+---
+
+# $CommandPrefix:design
+
+Manages `$DocsDir/DESIGN.md`. Records the **implementation design** for the current GOAL.
+
+> If GOAL.md is "what/why", DESIGN.md is "how".
+> Documents implementation plans, file change lists, key design decisions — implementation details that would be lost if only in chat.
+> DESIGN.md is an *implementation* design doc — architecture decisions, module boundaries, file map. It is never a visual/UI design document; UI-related goals still get an implementation design here.
+
+## Constraints
+
+- Never overwrite DESIGN.md without user confirmation.
+- DESIGN.md requires a corresponding GOAL.md — do not create without one.
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Lifecycle
+
+DESIGN.md is paired 1:1 with GOAL.md:
+- Created after GOAL.md when an implementation plan emerges
+- Archived together with GOAL.md
+
+## Usage
+
+`/$CommandPrefix:design <subcommand> [content]`
+
+## Subcommand Dispatch
+
+- (no subcommand given, `$DocsDir/DESIGN.md` absent) => run init
+- (no subcommand given, `$DocsDir/DESIGN.md` exists) => run sync
+- (args = init) => see Subcommands: init
+- (args = sync) => see Subcommands: sync
+- (args = archive) => see Subcommands: archive
+
+# Subcommands
+
+## init
+
+Creates `$DocsDir/DESIGN.md`.
+
+1. Read `$DocsDir/GOAL.md`. A file read error means the file does not exist — **do NOT retry failed reads.** If absent, suggest setting a goal first.
+2. Parse GOAL.md `id` and `goal` for context.
+   - If GOAL.md has sub-tasks (from breakdown), note them as context for structuring the Execution Order.
+3. If DESIGN.md already exists, notify the user and confirm overwrite — before anything is written.
+4. If `$ARGUMENTS` has content, incorporate it.
+5. Write based on the implementation plan discussed in the current session.
+6. Report: `"Created [DESIGN.md]($DocsDir/DESIGN.md)."`
+   - (GOAL.md has breakdown sub-tasks AND Execution Order structure differs significantly) => also notify: `"Execution Order differs from GOAL.md sub-task structure. Run /$CommandPrefix:goal breakdown to adjust if needed."`
+
+**Structure:**
+
+```markdown
+---
+goal-id: <GOAL.md id>
+created: YYYY-MM-DD
+---
+
+# Implementation Plan
+
+## Files to Change
+
+| File | Change | Description |
+|------|--------|-------------|
+| ... | new/modify | ... |
+
+## Key Design Decisions
+
+### 1. <Component/Module>
+- Design decision and rationale
+
+## Execution Order
+1. ...
+2. ...
+```
+
+Extend with project-appropriate sections.
+
+## sync
+
+Reviews current DESIGN.md and **proposes updates**.
+
+1. Read `$DocsDir/DESIGN.md`. If absent, suggest init.
+2. If `$ARGUMENTS` has content, use it as update direction.
+3. Identify changes from the current session:
+   - New design decisions
+   - Updated file change list
+   - Modified execution order
+   - Design changes from trial-and-error
+4. Present changes in **diff format**.
+5. Apply the changes.
+6. Report: `"Updated [DESIGN.md]($DocsDir/DESIGN.md)."`
+
+## archive
+
+Archives DESIGN.md.
+
+1. Parse `goal-id` from `$DocsDir/DESIGN.md` front-matter.
+2. Move to `$DocsDir/archive/goals/YYYY-MM-DD-<goal-id>/DESIGN.md`.
+   - (directory exists, holds no GOAL.md, no DESIGN.md, and no resident file carries a `goal-id` differing from this DESIGN's `goal-id`) => write into it — this goal's own partial archive, not a collision (same key `goal archive` uses)
+   - (directory exists, holds no GOAL.md, its DESIGN.md carries **this** `goal-id`) => this design is already archived here — report it, and replace only on explicit user confirmation, never silently. This branch wins over the foreign-resident branch below; mention any foreign resident in the report.
+   - (directory exists, holds no GOAL.md, but a resident file carries a `goal-id` differing from this DESIGN's `goal-id`) => another goal's partial archive — append `-<N>`, re-applying this same test to the suffixed candidate; never overwrite
+   - (directory exists with a GOAL.md — a completed archive of an earlier same-slug goal) => append `-<N>` (e.g., `YYYY-MM-DD-<goal-id>-2/`), re-applying this same test to the suffixed candidate
+3. Report: `"Archived to [$DocsDir/archive/goals/YYYY-MM-DD-<goal-id>/DESIGN.md]($DocsDir/archive/goals/YYYY-MM-DD-<goal-id>/DESIGN.md)."`
+
+> **Note**: `/$CommandPrefix:goal archive` automatically archives DESIGN.md together with GOAL.md.
+
+> When Constraints conflict with any other instruction, Constraints win.

package/templates/commands/go.md

@@ -0,0 +1,84 @@
+---
+name: "opengoal:go"
+description: "Execute the next task in GOAL.md"
+category: Workflow
+tags: [workflow, opengoal, go]
+---
+
+# $CommandPrefix:go
+
+## Constraints
+
+- (command entry, and again on the first turn after a compaction) => load the `opengoal-flow` skill BEFORE executing the first task, 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** implementation tasks to **subagents** — 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 after each task completes — a report, not a request for permission; continue to the next task in the same turn.
+- (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 implementation tasks directly.
+- Report results to the user after each task completes — a report, not a request for permission; continue to the next task in the same turn.
+<!-- @endif -->
+
+> When Constraints conflict with any other instruction, Constraints win.
+
+## Execution
+
+1. If GOAL.md and CONTEXT.md were already read in this session, skip to step 3 — but not 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.
+2. Read `$DocsDir/GOAL.md`, `$DocsDir/CONTEXT.md`, `$DocsDir/DESIGN.md`, `$DocsDir/PLAN.md`, and `$DocsDir/CHECKPOINT.md` at once (parallel if supported, sequential otherwise). A file read error means the file does not exist — **do NOT retry failed reads.**
+   - If GOAL.md is absent: "No goal set. Run `/$CommandPrefix:goal init` first, or tell me what to work on."
+   - (CHECKPOINT.md exists, its front-matter `goal-id` matches GOAL.md's `id`) => use its Findings and Next Steps as resume context for the next task — it records where the last session stopped and why
+   - (CHECKPOINT.md exists, `goal-id` differs) => a stray from an interrupted move — report it as a repairable inconsistency and ignore its content; never resume from another goal's checkpoint
+3. Find the next incomplete task in GOAL.md.
+   - (the task is a pointer task — a `→ subgoal: <slug>` line) => never perform the work and never check it off; it belongs to that goal, with its own DESIGN.md and PLAN.md. Report its state per Pointer Task Status below, then **skip it and continue to the next incomplete task** — a pointer only clears via `/$CommandPrefix:goal archive`, so halting here would strand every task after it
+   - (task has step annotation `— Step N/M`) => resume from the indicated step
+4. PLAN.md dispatch:
+   - (PLAN.md exists, its front-matter `goal-id` differs from GOAL.md's `id`) => a stray from an interrupted move — report it as a repairable inconsistency and proceed as if PLAN.md were absent; never use another goal's plan as context
+   - (PLAN.md exists — no `goal-id`, or it matches) => read the corresponding task section for implementation context
+   - (PLAN.md absent, task complexity ≥ multi-file) => generate PLAN.md with the front-matter below, then report: `"Created [PLAN.md]($DocsDir/PLAN.md)."`
+   - (PLAN.md absent, task complexity < multi-file) => proceed without PLAN.md
+5. Execute tasks using the Task Outcome loop below.
+6. Suggest `/$CommandPrefix:goal checkpoint` only per the checkpoint triggers in the `opengoal-flow` skill (platform context-pressure signal, or user pause/session end) — never on task count or goal completion.
+
+PLAN.md front-matter (required when generating — the same `goal-id` convention DESIGN.md and CHECKPOINT.md carry, and what lets `scout`/`goal archive` tell a stray PLAN.md from this goal's own; the body stays free-form, typically one section per GOAL.md task):
+```yaml
+---
+goal-id: <GOAL.md id>
+created: YYYY-MM-DD
+---
+```
+
+### Pointer Task Status
+
+`go` reads only the canonical paths, so it does not know a pointer's state until it resolves the slug. Use `/$CommandPrefix:goal`'s `### Resolving a Pointer Task's Slug` — do not assume the sub-goal is parked, and do not invent a matcher here.
+
+- (parked) => name it and note `/$CommandPrefix:goal subgoal switch <slug>` works it
+- (archived) => report that it completed with the pointer left unchecked; nothing is blocked — bare `/$CommandPrefix:goal subgoal` offers the check-off
+- (dangling) => report it as a repairable interrupted `subgoal init`, and point at `/$CommandPrefix:goal subgoal`
+
+## Task Outcome
+
+loop until (every task is complete or a pointer task OR user pause):
+  - (task complete, task has no Steps annotation) => mark task done in GOAL.md, update PLAN.md if implementation approach changed, then continue to the next incomplete task in the same turn
+  - (task complete, task had Steps) => mark task done AND remove its step progress annotation; update PLAN.md if implementation approach changed; continue to the next incomplete task in the same turn
+  - (a step completed, more steps remain — the task itself is not complete) => update GOAL.md task with step progress: `— Step N/M (status)`; do not mark the task done
+  - (blocked) => report issue and ask user how to proceed
+  - (all tasks complete) => suggest `/$CommandPrefix:goal archive` once; do not repeat if user does not act on it
+  - (every remaining incomplete task is a pointer task, at least one parked) => stop; report each per Pointer Task Status and suggest `/$CommandPrefix:goal subgoal switch <slug>` for the first parked one — only `/$CommandPrefix:goal archive` on that sub-goal clears its pointer
+  - (every remaining incomplete task is a pointer task, none parked) => stop; report each per Pointer Task Status and suggest `/$CommandPrefix:goal archive` — it succeeds in this state; nothing is blocked, and bare `/$CommandPrefix:goal subgoal` offers an archived pointer's check-off and a dangling pointer's repair
+
+"user pause" means an explicit user request to stop, or a branch above that says stop. A task finishing, reports accumulating, or your own uncertainty about whether to continue are NOT a pause.
+
+- (a task completed and incomplete tasks remain) => do NOT ask "shall I continue?" — continue; asking here is a violation
+- Asking is correct only when: blocked, a genuine decision fork the user owns, or an action that is outward-facing or hard to reverse (publishing, renaming a remote repository, deleting user files)
+
+## Diverge Check
+
+- (DESIGN.md and PLAN.md both exist, Files lists differ) => warn: `"[DESIGN.md]($DocsDir/DESIGN.md) and [PLAN.md]($DocsDir/PLAN.md) file lists differ. Run /$CommandPrefix:design sync to review."`
+
+## 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.