@opellen/opengoal 1.0.5 → 1.1.0-rc.1

package/README.ja.md

@@ -330,9 +330,9 @@ AI:  ✓ サブゴールをアーカイブしました。Goal Aに戻ります
 
 **長期にわたるビルド**
 
-- [Planura](https://github.com/opellen/Planura) — ネイティブなダイレクトモデリング3Dアプリケーション(C++20 / Qt 6 / OpenGL): half-edgeジオメトリカーネル、CSGソリッドモデリング、推論駆動の描画を、専用フレームワーク [Ordo](https://github.com/opellen/Ordo) の上に実装。
-- [Ordo](https://github.com/opellen/Ordo) — Planura から切り出された C++20 の型付きイベント・アプリケーションフレームワークです。イベントはただの構造体で、型がアイデンティティ、フィールドがペイロードです。
+- [Ordo](https://github.com/opellen/Ordo) — C++20 の型付きイベント・アプリケーションフレームワークです。イベントはただの構造体で、型がアイデンティティ、フィールドがペイロードです。OrdoStateDesigner と Planura はこの上に構築されています。
 - [OrdoStateDesigner](https://github.com/opellen/OrdoStateDesigner) — Ordo の上に構築したステートチャート・デザイナー(C++20 / Qt 6)です。キャンバスに状態機械を描き、その場でシミュレートし、それを動かす C++ を生成します。
+- [Planura](https://github.com/opellen/Planura) — ネイティブなダイレクトモデリング3Dアプリケーション(C++20 / Qt 6 / OpenGL): half-edgeジオメトリカーネル、CSGソリッドモデリング、推論駆動の描画を Ordo の上に実装。Ordo はこのプロジェクトから切り出されたものです。
 - リバースエンジニアリングのキャンペーン — OpenGoalが設計された本来の領域であり、ゴールは大きく、道筋は不明で、進捗が細かく分割できるかどうかにかかっています。
 
 **アプリケーションとツール**

package/README.ko.md

@@ -328,13 +328,13 @@ AI:  ✓ 서브골 아카이브 완료. Goal A로 복귀 — 포인터 태스크
 
 **긴 호흡의 개발**
 
-- [Planura](https://github.com/opellen/Planura) — 네이티브 다이렉트 모델링 3D 애플리케이션
-  (C++20 / Qt 6 / OpenGL). half-edge 지오메트리 커널, CSG 솔리드 모델링, 추론 기반 드로잉을
-  자체 프레임워크인 [Ordo](https://github.com/opellen/Ordo) 기반으로 구현했습니다.
-- [Ordo](https://github.com/opellen/Ordo) — Planura에서 추출된 C++20용 타입 이벤트 애플리케이션 프레임워크입니다.
-  이벤트는 평범한 구조체이며, 타입이 곧 정체성이고 필드가 곧 페이로드입니다.
+- [Ordo](https://github.com/opellen/Ordo) — C++20용 타입 이벤트 애플리케이션 프레임워크입니다.
+  이벤트는 평범한 구조체이며, 타입이 곧 정체성이고 필드가 곧 페이로드입니다. OrdoStateDesigner와 Planura가 이 위에서 만들어졌습니다.
 - [OrdoStateDesigner](https://github.com/opellen/OrdoStateDesigner) — Ordo 기반의 상태차트 디자이너입니다
   (C++20 / Qt 6). 캔버스에 상태 머신을 그리고, 실시간으로 시뮬레이션하고, 그것을 실행하는 C++ 코드를 생성합니다.
+- [Planura](https://github.com/opellen/Planura) — 네이티브 다이렉트 모델링 3D 애플리케이션
+  (C++20 / Qt 6 / OpenGL). half-edge 지오메트리 커널, CSG 솔리드 모델링, 추론 기반 드로잉을
+  Ordo 기반으로 구현했고, Ordo는 이 프로젝트에서 추출됐습니다.
 - 리버스엔지니어링 캠페인 — OpenGoal이 처음 고안된 도메인입니다. 목표는 거대하고 길은
   보이지 않아서, 목표를 잘게 쪼갤 수 있을 때에만 전진할 수 있는 영역입니다.
 

package/README.md

@@ -336,13 +336,13 @@ That range is the point.
 
 **Long-horizon builds**
 
-- [Planura](https://github.com/opellen/Planura) — a native direct-modeling 3D application
-  (C++20 / Qt 6 / OpenGL): half-edge geometry kernel, CSG solid modeling, inference-driven
-  drawing, on [Ordo](https://github.com/opellen/Ordo), its purpose-built application framework.
-- [Ordo](https://github.com/opellen/Ordo) — a typed-event application framework for C++20, extracted from
-  Planura. An event is a plain struct: the type is the identity, the fields are the payload.
+- [Ordo](https://github.com/opellen/Ordo) — a typed-event application framework for C++20. An event is a
+  plain struct: the type is the identity, the fields are the payload. OrdoStateDesigner and Planura are built on it.
 - [OrdoStateDesigner](https://github.com/opellen/OrdoStateDesigner) — a statechart designer built on Ordo
   (C++20 / Qt 6): draw a state machine on a canvas, simulate it live, and generate the C++ that runs it.
+- [Planura](https://github.com/opellen/Planura) — a native direct-modeling 3D application
+  (C++20 / Qt 6 / OpenGL): half-edge geometry kernel, CSG solid modeling, inference-driven
+  drawing, on Ordo, which was extracted from it.
 - Reverse-engineering campaigns — the domain OpenGoal was designed in, where the goal is
   large, the path is unknown, and progress depends on splitting it finely.
 

package/README.zh-CN.md

@@ -351,13 +351,13 @@ AI:  ✓ sub-goal 已归档。回到目标 A —— 对应的指针任务已勾
 
 **长周期开发**
 
-- [Planura](https://github.com/opellen/Planura) — 一款原生的直接建模 3D 应用
-  （C++20 / Qt 6 / OpenGL）：半边（half-edge）几何内核、CSG 实体建模、推理驱动的
-  绘图，构建在自研框架 [Ordo](https://github.com/opellen/Ordo) 之上。
-- [Ordo](https://github.com/opellen/Ordo) — 从 Planura 中提取出来的 C++20 类型化事件应用框架。
-  事件就是一个普通的结构体：类型即身份，字段即载荷。
+- [Ordo](https://github.com/opellen/Ordo) — C++20 类型化事件应用框架。
+  事件就是一个普通的结构体：类型即身份，字段即载荷。OrdoStateDesigner 和 Planura 都构建在它之上。
 - [OrdoStateDesigner](https://github.com/opellen/OrdoStateDesigner) — 构建在 Ordo 之上的状态图设计器
   （C++20 / Qt 6）：在画布上绘制状态机，实时模拟，并生成运行它的 C++ 代码。
+- [Planura](https://github.com/opellen/Planura) — 一款原生的直接建模 3D 应用
+  （C++20 / Qt 6 / OpenGL）：半边（half-edge）几何内核、CSG 实体建模、推理驱动的
+  绘图，构建在 Ordo 之上；Ordo 正是从这个项目中提取出来的。
 - 逆向工程项目 — OpenGoal 最初就是为这类场景设计的：目标庞大、路径未知，
   进展全靠把任务拆得足够细。
 

package/dist/cli.js

@@ -3,7 +3,7 @@ import { resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { install, dryRun, detectStale, removeStale } from "./installer.js";
 import { DEFAULT_PREFIX } from "./templates.js";
-import { PLATFORM_IDS, DEFAULT_PLATFORM, isValidPlatform, detectInstalledPlatforms } from "./platforms/index.js";
+import { PLATFORM_IDS, DEFAULT_PLATFORM, isValidPlatform, detectInstalledPlatforms, getAdapters } from "./platforms/index.js";
 import { showWelcome } from "./ui/welcome.js";
 import { selectPlatforms } from "./prompts/platform-select.js";
 import { t } from "./i18n/index.js";
@@ -250,7 +250,7 @@ async function main() {
             console.log(`  ${chalk.green("+")} ${file}`);
         }
         if (stale.length > 0) {
-            console.log("\nStale files from a previous prefix (would be removed):");
+            console.log("\nStale files from a previous prefix or install layout (would be removed):");
             for (const entry of stale) {
                 console.log(`  ${chalk.red("-")} ${entry.dst}`);
             }
@@ -272,7 +272,7 @@ async function main() {
         }
     }
     if (stale.length > 0) {
-        console.log("\nStale files from a previous prefix:");
+        console.log("\nStale files from a previous prefix or install layout:");
         for (const entry of stale) {
             console.log(`  ${chalk.yellow("!")} ${entry.dst}`);
         }
@@ -292,7 +292,20 @@ async function main() {
     }
     console.log("\n" + title(t("cli.nextSteps")));
     console.log("  " + chalk.dim("1.") + " " + t("cli.step1"));
-    console.log("  " + chalk.dim("2.") + " " + t("cli.step2").replace("{cmd}", goal(`/${args.prefix}:scout`)));
+    const hints = new Map();
+    for (const adapter of getAdapters(tools)) {
+        if (adapter.supportsCommands === false)
+            continue;
+        const ref = adapter.commandRef?.("scout", args.prefix) ?? `/${args.prefix}:scout`;
+        const labels = hints.get(ref) ?? [];
+        if (!labels.includes(adapter.displayName))
+            labels.push(adapter.displayName);
+        hints.set(ref, labels);
+    }
+    for (const [ref, labels] of hints) {
+        const label = tools.length > 1 ? `${labels.join(", ")}: ` : "";
+        console.log("  " + chalk.dim("2.") + " " + label + t("cli.step2").replace("{cmd}", goal(ref)));
+    }
     process.exit(0);
 }
 main();

package/dist/installer.d.ts

@@ -16,6 +16,12 @@ export declare function dryRun(config: OpenGoalConfig): {
  * eligible. Skill entries are excluded (rule: skills don't carry the
  * prefix, so they can never go stale), and the current prefix is never
  * considered stale even if passed in explicitly.
+ *
+ * Adapters that declare legacyLayouts (an earlier config dir / command
+ * layout) additionally contribute the exact files opengoal wrote there, for
+ * the current prefix and every old prefix, plus the shared skills (once).
+ * Such entries carry an adapter view whose configDir is the legacy root, so
+ * removeStale() prunes emptied directories up to that root.
  */
 export declare function detectStale(config: OpenGoalConfig, oldPrefixes: string[]): TemplateEntry[];
 /**

package/dist/installer.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, writeFileSync, unlinkSync, readdirSync, rmdirSync } from "node:fs";
 import { createInterface } from "node:readline";
 import { join, dirname, resolve, sep } from "node:path";
+import { getAdapters } from "./platforms/index.js";
 import { resolveTemplates, renderFile } from "./templates.js";
 function createDefaultPrompt() {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -80,6 +81,12 @@ export function dryRun(config) {
  * eligible. Skill entries are excluded (rule: skills don't carry the
  * prefix, so they can never go stale), and the current prefix is never
  * considered stale even if passed in explicitly.
+ *
+ * Adapters that declare legacyLayouts (an earlier config dir / command
+ * layout) additionally contribute the exact files opengoal wrote there, for
+ * the current prefix and every old prefix, plus the shared skills (once).
+ * Such entries carry an adapter view whose configDir is the legacy root, so
+ * removeStale() prunes emptied directories up to that root.
  */
 export function detectStale(config, oldPrefixes) {
     const seen = new Set();
@@ -99,8 +106,45 @@ export function detectStale(config, oldPrefixes) {
             }
         }
     }
+    stale.push(...detectLegacyLayoutFiles(config, oldPrefixes, seen));
     return stale;
 }
+function detectLegacyLayoutFiles(config, oldPrefixes, seen) {
+    const found = [];
+    const current = new Set(resolveTemplates(config).map((e) => e.dst));
+    const prefixes = Array.from(new Set([config.prefix, ...oldPrefixes]));
+    for (const adapter of getAdapters(config.tools)) {
+        if (!adapter.legacyLayouts)
+            continue;
+        for (const layout of adapter.legacyLayouts) {
+            const view = { ...adapter, configDir: layout.configDir };
+            const consider = (entry, dst) => {
+                if (current.has(dst) || seen.has(dst))
+                    return;
+                seen.add(dst);
+                if (existsSync(join(config.root, dst)))
+                    found.push({ ...entry, dst, adapter: view });
+            };
+            prefixes.forEach((prefix, i) => {
+                const entries = resolveTemplates({ ...config, tools: [adapter.id], prefix });
+                for (const entry of entries) {
+                    if (entry.generated)
+                        continue;
+                    if (entry.src.startsWith("commands/")) {
+                        if (adapter.supportsCommands === false)
+                            continue;
+                        const cmd = entry.src.slice("commands/".length).replace(/\.md$/, "");
+                        consider(entry, layout.commandPath(cmd, prefix));
+                    }
+                    else if (i === 0 && entry.src.startsWith("skills/")) {
+                        consider(entry, `${layout.configDir}/skills/${entry.meta.name}/SKILL.md`);
+                    }
+                }
+            });
+        }
+    }
+    return found;
+}
 /**
  * Walks upward from startDir, removing directories that are now empty,
  * stopping at (and never removing) boundaryDir itself, and stopping as
@@ -140,7 +184,7 @@ export async function removeStale(config, stale, prompt) {
     try {
         let proceed = config.force === true;
         if (!proceed) {
-            const answer = await askUser(`  Found ${stale.length} stale command file(s) from a previous prefix. Remove? [y/N] `);
+            const answer = await askUser(`  Found ${stale.length} stale command file(s) from a previous prefix or install layout. Remove? [y/N] `);
             proceed = answer === "y" || answer === "yes";
         }
         if (!proceed) {

package/dist/platforms/antigravity.js

@@ -1,12 +1,21 @@
 import { stripFrontmatter, yamlFrontmatter } from "./yaml.js";
+// Antigravity merged slash-command workflows into skills and moved its
+// workspace dir from `.agent/` to `.agents/`. A skill is invoked as `/<name>`.
 export const antigravity = {
     id: "antigravity",
     displayName: "Antigravity",
-    configDir: ".agent",
-    commandPath: (name, prefix) => `.agent/workflows/${prefix}-${name}.md`,
-    formatCommand: (body, meta) => {
-        const stripped = stripFrontmatter(body);
-        const fm = yamlFrontmatter({ description: meta.description });
-        return fm + stripped;
-    },
+    configDir: ".agents",
+    commandPath: (name, prefix) => `.agents/skills/${prefix}-${name}/SKILL.md`,
+    formatCommand: (body, meta, prefix) => yamlFrontmatter({ name: `${prefix}-${meta.name}`, description: meta.description }) +
+        stripFrontmatter(body),
+    commandRef: (name, prefix) => `/${prefix}-${name}`,
+    legacyLayouts: [
+        {
+            configDir: ".agent",
+            commandPath: (name, prefix) => `.agent/workflows/${prefix}-${name}.md`,
+        },
+    ],
+    // `.agents/skills/` is the cross-tool Agent Skills root (Codex and others
+    // read it too), so only Antigravity-specific dirs count as detection.
+    detectDirs: [".agent", ".agents/workflows", ".agents/rules"],
 };

package/dist/platforms/index.d.ts

@@ -1,7 +1,7 @@
 import type { PlatformAdapter } from "./types.js";
 export type { PlatformAdapter, CommandMeta } from "./types.js";
 export { DEFAULT_PLATFORM } from "./types.js";
-export declare const PLATFORM_IDS: readonly ["claude", "cursor", "windsurf", "cline", "codex", "github-copilot", "continue", "amazon-q", "antigravity", "auggie", "codebuddy", "costrict", "crush", "factory", "gemini", "iflow", "kilocode", "kiro", "opencode", "pi", "qoder", "qwen", "roocode", "trae"];
+export declare const PLATFORM_IDS: readonly ["claude", "cursor", "windsurf", "cline", "codex", "github-copilot", "continue", "amazon-q", "antigravity", "auggie", "codebuddy", "costrict", "crush", "factory", "gemini", "iflow", "kilocode", "kiro", "kimi", "opencode", "pi", "qoder", "qwen", "roocode", "trae"];
 export type PlatformId = typeof PLATFORM_IDS[number];
 export declare function isValidPlatform(id: string): id is PlatformId;
 export declare function getAdapter(id: string): PlatformAdapter | undefined;

package/dist/platforms/index.js

@@ -24,11 +24,12 @@ import { qoder } from "./qoder.js";
 import { qwen } from "./qwen.js";
 import { roocode } from "./roocode.js";
 import { trae } from "./trae.js";
+import { kimi } from "./kimi.js";
 export { DEFAULT_PLATFORM } from "./types.js";
 const ALL_ADAPTERS = [
     claude, cursor, windsurf, cline, codex, githubCopilot, continueAdapter,
     amazonQ, antigravity, auggie, codebuddy, costrict, crush, factory,
-    gemini, iflow, kilocode, kiro, opencode, pi, qoder, qwen, roocode, trae,
+    gemini, iflow, kilocode, kiro, kimi, opencode, pi, qoder, qwen, roocode, trae,
 ];
 const ADAPTER_MAP = new Map(ALL_ADAPTERS.map((a) => [a.id, a]));
 if (ADAPTER_MAP.size !== ALL_ADAPTERS.length)
@@ -36,7 +37,7 @@ if (ADAPTER_MAP.size !== ALL_ADAPTERS.length)
 export const PLATFORM_IDS = [
     "claude", "cursor", "windsurf", "cline", "codex", "github-copilot", "continue",
     "amazon-q", "antigravity", "auggie", "codebuddy", "costrict", "crush", "factory",
-    "gemini", "iflow", "kilocode", "kiro", "opencode", "pi", "qoder", "qwen", "roocode", "trae",
+    "gemini", "iflow", "kilocode", "kiro", "kimi", "opencode", "pi", "qoder", "qwen", "roocode", "trae",
 ];
 if (PLATFORM_IDS.length !== ALL_ADAPTERS.length)
     throw new Error("PLATFORM_IDS out of sync");
@@ -60,7 +61,9 @@ export function getAllAdapters() {
 export function detectInstalledPlatforms(projectRoot) {
     const detected = [];
     for (const adapter of ALL_ADAPTERS) {
-        if (existsSync(resolve(projectRoot, adapter.configDir))) {
+        const dirs = adapter.detectDirs ??
+            [adapter.configDir, ...(adapter.legacyLayouts?.map((l) => l.configDir) ?? [])];
+        if (dirs.some((dir) => existsSync(resolve(projectRoot, dir)))) {
             detected.push(adapter.id);
         }
     }

package/dist/platforms/kimi.d.ts

@@ -0,0 +1,2 @@
+import type { PlatformAdapter } from "./types.js";
+export declare const kimi: PlatformAdapter;

package/dist/platforms/kimi.js

@@ -0,0 +1,10 @@
+import { stripFrontmatter, yamlFrontmatter } from "./yaml.js";
+export const kimi = {
+    id: "kimi",
+    displayName: "Kimi Code",
+    configDir: ".kimi-code",
+    commandPath: (name, prefix) => `.kimi-code/skills/${prefix}-${name}/SKILL.md`,
+    formatCommand: (body, meta, prefix) => yamlFrontmatter({ name: `${prefix}-${meta.name}`, description: meta.description }) +
+        stripFrontmatter(body),
+    commandRef: (name, prefix) => `/skill:${prefix}-${name}`,
+};

package/dist/platforms/types.d.ts

@@ -43,5 +43,22 @@ export interface PlatformAdapter {
      * uninstalled together with the file they accompany.
      */
     companionFiles?(target: CompanionTarget): CompanionFile[];
+    /**
+     * Earlier install layouts of this platform (e.g. a renamed config dir).
+     * Re-installing offers to remove the files opengoal itself wrote there,
+     * found by exact path (never a glob). `configDir` is the root that emptied
+     * directories are pruned up to; the root itself is never removed.
+     */
+    legacyLayouts?: Array<{
+        configDir: string;
+        commandPath(name: string, prefix: string): string;
+    }>;
+    /**
+     * Directories whose presence means this platform is in use, for
+     * auto-detection. Defaults to `configDir` plus every legacy `configDir`.
+     * Set it when `configDir` is a root other tools share (e.g. `.agents/`),
+     * so that root alone does not count as detection.
+     */
+    detectDirs?: string[];
 }
 export declare const DEFAULT_PLATFORM = "claude";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opellen/opengoal",
-  "version": "1.0.5",
+  "version": "1.1.0-rc.1",
   "description": "Goal-centric AI harness. Plain markdown, zero runtime — nothing runs but your agent.",
   "type": "module",
   "license": "MIT",

package/templates/commands/context.md

@@ -15,7 +15,9 @@ Manages `$DocsDir/CONTEXT.md`. Records the **current working context** of the pr
 ## Constraints
 
 - Never overwrite CONTEXT.md without user confirmation.
-- Target ~100 lines or less — this file is read at every session start.
+- Writes `$DocsDir/CONTEXT.md` only — content that belongs in another resource is reported to the user, never written there.
+- Pointers only — this file is read whole at every session start, so an entry records when to read a resource and where it is, never what is learned after opening it.
+- (an entry restates what its referenced resource already holds) => reduce it to the pointer.
 
 > When Constraints conflict with any other instruction, Constraints win.
 
@@ -70,9 +72,9 @@ Creates `$DocsDir/CONTEXT.md`.
 
 **Project-specific sections** — extend the skeleton with sections appropriate to the project:
 
-- **Resources**: Key file/directory paths and their descriptions
+- **Resources**: Key file/directory paths and when to reference them, not their contents
 - **Process**: Project-specific procedures (e.g., porting rules, analysis doc management)
-- **Index/Tables**: Frequently referenced item lists (e.g., analysis topics, API endpoints)
+- **Index/Tables**: Frequently referenced item lists (e.g., analysis topics, API endpoints). When the list lives in its own file, this section holds the pointer to that file, not a copy of the list.
 - **Extended Principles**: Project-specific principles (e.g., 1:1 logic preservation, no magic numbers)
 
 ## sync
@@ -86,6 +88,8 @@ Reviews current CONTEXT.md and **proposes updates**.
    - Content to add
    - Content to modify
    - Outdated content to remove/update
+   - Entries to reduce to a pointer — the referenced resource already holds the content
+   - Entries whose content no resource holds yet — listed as move candidates for the user; sync does not write outside CONTEXT.md
 5. Apply the changes.
 6. Report: `"Updated [CONTEXT.md]($DocsDir/CONTEXT.md)."`
 

package/templates/commands/go.md

@@ -1,84 +1,87 @@
----
-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.
+---
+name: "opengoal:go"
+description: "Execute the next task in GOAL.md"
+category: Workflow
+tags: [workflow, opengoal, go]
+---
+
+# $CommandPrefix:go
+
+## Constraints
+
+- (command entry, `opengoal-flow`'s own text not visible in your current context) => load the `opengoal-flow` skill BEFORE executing the first task, and say so in one line — its rules (checkpoint triggers, documentation timing, CONTEXT.md self-sync, self-verification) bind only while that text is in context.
+- (command entry, `opengoal-flow`'s own text visible) => do not re-read it.
+- Visible means the skill's text itself, as read or injected — remembering its rules, or a summary that mentions them, is not visible.
+<!-- @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.
+- (subagent dispatch, `opengoal-subagent`'s own text not visible in your current context) => 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 and announcement is a violation, because its dispatch rules (model selection/reporting, prompt requirements, post-verify) bind only while that text is in context.
+- (subagent dispatch, `opengoal-subagent`'s own text visible) => do not re-read it.
+<!-- @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 the text of GOAL.md and CONTEXT.md is visible in your current context, 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.

package/templates/commands/goal.md

@@ -1,6 +1,6 @@
 ---
 name: "opengoal:goal"
-description: "Project goal (GOAL.md) management (init|breakdown|checkpoint|suspend|resume|archive)"
+description: "Project goal (GOAL.md) management (init|breakdown|checkpoint|suspend|resume|archive|land)"
 category: Workflow
 tags: [workflow, opengoal, goal]
 ---
@@ -11,12 +11,16 @@ Manages `$DocsDir/GOAL.md`.
 
 ## Constraints
 
-- (command entry, and again on the first turn after a compaction) => load the `opengoal-flow` skill BEFORE writing or moving any document, and say so in one line. A reference is not a load: its rules (self-verification before marking anything done, User Decision Support format) only bind once the skill's content is actually in context.
+- (command entry, `opengoal-flow`'s own text not visible in your current context) => load the `opengoal-flow` skill BEFORE writing or moving any document, and say so in one line — its rules (self-verification before marking anything done, User Decision Support format) bind only while that text is in context.
+- (command entry, `opengoal-flow`'s own text visible) => do not re-read it.
+- Visible means the skill's text itself, as read or injected — remembering its rules, or a summary that mentions them, is not visible.
 - GOAL.md is the single source of truth for the current goal's state.
-- Never overwrite GOAL.md without user confirmation.
+- Never overwrite GOAL.md — a second goal while one is active goes through the four options in `### init (active goal present)` (worktree / suspend / archive / cancel); none of them overwrites.
 - Preserve existing check states when updating tasks.
 - Task numbers use hierarchical dot notation: `1.`, `1.1.`, `1.2.1.` — numbers are part of the checklist text, no separate id field.
 - (`subgoal init`, the derived slug matches `$DocsDir/suspended/<slug>/` or the active goal's `id`) => refuse outright and ask for a different description — never offer to overwrite; a dangling `→ subgoal: <slug>` pointer task is not a collision (an interrupted `init` must stay re-runnable), and `$DocsDir/archive/` is deliberately not checked because `archive`'s `-<N>` directory rule makes an archived slug safe to reuse.
+- (`land`, the merge reports a conflict) => abort the merge and report the conflicting files — never edit conflict hunks on your own; which side wins is the user's call.
+- (`archive` or `land` running inside a worktree, per `### Worktree Detection`) => never modify the main checkout's working tree except through `land`'s own `git -C <main-root> merge` and its `--abort` — merge timing across worktrees belongs to the user.
 
 > When Constraints conflict with any other instruction, Constraints win.
 
@@ -26,6 +30,8 @@ Manages `$DocsDir/GOAL.md`.
 
 `/$CommandPrefix:goal subgoal <verb> [args]` — sub-goal lifecycle (`init` | `pause` | `switch`, or no verb to list).
 
+`/$CommandPrefix:goal land [<id>]` — merge a finished worktree goal into the base branch (runnable from any session).
+
 `/$CommandPrefix:goal <goal description>` — shorthand for `init` with that content.
 
 ## Subcommand Dispatch
@@ -43,6 +49,7 @@ Manages `$DocsDir/GOAL.md`.
 - (args = subgoal) => see Subcommands: subgoal
 - (args = archive, `$DocsDir/GOAL.md` absent) => stop: "No active GOAL to archive."
 - (args = archive, GOAL.md exists) => see Subcommands: archive
+- (args = land) => see Subcommands: land — it resolves its own target and needs no active GOAL.md
 - (args are free-text goal content — multi-word or quoted, not a subcommand keyword — and `$DocsDir/GOAL.md` has `parent:`) => refuse with the same message as `args = init` — free text runs init
 - (args are free-text goal content — multi-word or quoted, not a subcommand keyword — and no `parent:`) => run init with that content
 - (otherwise) => report unknown subcommand and list available subcommands
@@ -58,8 +65,8 @@ Creates `$DocsDir/GOAL.md`.
 
 1. If `$ARGUMENTS` has content, use it to write the goal.
 2. If empty, derive from the current session discussion.
-3. If GOAL.md already exists, notify the user and confirm overwrite.
-4. Write GOAL.md with the format below.
+3. If GOAL.md already exists, run `### init (active goal present)` below. It either stops (cancel, or the new goal was created in a worktree) or returns here with the canonical slot empty.
+4. Write GOAL.md with the format below. (picked from a `$DocsDir/ROADMAP.md` milestone) => record `milestone: M<N>`; (the description names a code area) => record `scope:`.
 5. Assess task granularity:
    - (tasks are complex, embed multiple implicit steps) => recommend `/$CommandPrefix:goal breakdown` with 1-line rationale
    - (tasks are specific and actionable) => recommend `/$CommandPrefix:design init` (implementation task) or `/$CommandPrefix:go` (analysis task) with 1-line rationale
@@ -75,6 +82,10 @@ id: <goal-slug>
 goal: <one-line summary>
 status: in-progress
 started: YYYY-MM-DD
+milestone: M<N>            # optional — the ROADMAP milestone this goal implements
+scope: [<dir>, <dir>]      # optional — code areas this goal expects to touch
+base: <branch>             # worktree goals only — the branch the worktree was forked from
+worktree: .opengoal/worktrees/<goal-slug>   # worktree goals only
 ---
 ```
 
@@ -90,6 +101,52 @@ Body structure:
 - Top-level tasks are numbered `1.`, `2.`, `3.`.
 - Sub-tasks inherit parent number: `1.1.`, `1.2.`, and deeper: `1.2.1.`, `1.2.2.`.
 
+### Worktree Detection
+
+Used by `init`, `archive`, `land`, and `/$CommandPrefix:scout`. Decide once per command run:
+
+- `<main-root>` = the first `worktree` line of `git worktree list --porcelain`.
+- This session is **inside a worktree** when `git rev-parse --show-toplevel` lies under `<main-root>/.opengoal/worktrees/`. GOAL.md's `worktree:` field confirms it but is not required — a goal started by hand in such a directory still counts.
+- Otherwise this session is in the **main checkout**.
+
+### init (active goal present)
+
+`$DocsDir/GOAL.md` exists and carries no `parent:` (a `parent:` is refused by Subcommand Dispatch before reaching here). The user's intent is ambiguous — a parallel goal, a forgotten archive, or a quick switch — so this is a genuine decision fork. Present it in `opengoal-flow`'s User Decision Support form as plain text (never a menu widget), with exactly one recommendation:
+
+```
+Active goal <id> is in progress. Options:
+1. New worktree — keep <id> running; start the new goal in .opengoal/worktrees/<new-id>/ for a separate session.
+2. Suspend <id> and start the new goal here.
+3. Archive <id> and start the new goal here.
+4. Cancel.
+```
+
+Pick the recommendation by the first rule that matches:
+
+- (the active goal has no incomplete tasks) => recommend 3
+- (this session is inside a worktree per `### Worktree Detection`) => omit option 1 from the menu — worktrees are created from the main checkout — and recommend 2
+- (the new goal maps to a ROADMAP milestone, or is clearly multi-session work) => recommend 1
+- (otherwise) => recommend 2
+
+Then:
+
+- (1) => run `#### init in a new worktree` below, and stop — do not continue `init` steps 4–7 here.
+- (2) => perform the `suspend` procedure, replacing its step 5 report with the single line `"Suspended <id> to [$DocsDir/suspended/<id>/]($DocsDir/suspended/<id>/)."`, then continue `init` at step 4.
+- (3) => perform the `archive` procedure, keeping its step 6 report but dropping the closer sentence, then continue `init` at step 4. Inside a worktree this runs `### archive (inside a worktree)` too; the new goal then continues on the same branch, and the worktree is merge-ready again only when that goal archives.
+- (4) => stop: `"Cancelled. Active goal <id> is unchanged."`
+
+#### init in a new worktree
+
+Run from the main checkout. Only the main checkout may create worktrees — (this session is inside a worktree per `### Worktree Detection`) => stop: `"Worktrees are created from the main checkout. Run /$CommandPrefix:goal init there."`
+
+1. Derive `<new-id>` the way `init` derives `id` (kebab-case English slug of the description). (`.opengoal/worktrees/<new-id>/` exists, branch `goal/<new-id>` exists, `$DocsDir/suspended/<new-id>/` exists, or `<new-id>` equals the active goal's `id`) => refuse and ask for a different description.
+2. Preflight: `git status --porcelain -- $DocsDir` on the main checkout must print nothing — a worktree is a checkout of HEAD, so uncommitted docs would be invisible to the new goal. (not clean) => report the files and stop; the user commits first.
+3. Record `<base>` = the branch currently checked out in the main checkout (`git rev-parse --abbrev-ref HEAD`); (`.gitignore` lacks a line covering `.opengoal/`) => append `.opengoal/` to `.gitignore` and say so.
+4. `git worktree add .opengoal/worktrees/<new-id> -b goal/<new-id>`.
+5. In the new worktree, delete the copied goal-owned documents: `$DocsDir/GOAL.md`, `$DocsDir/DESIGN.md`, `$DocsDir/PLAN.md`, `$DocsDir/CHECKPOINT.md` (whichever exist). They belong to the goal still running in the main checkout; `archive`'s worktree closing steps make these deletions merge-neutral.
+6. Write the new goal's GOAL.md at `.opengoal/worktrees/<new-id>/$DocsDir/GOAL.md` using the format above, including `base: <base>` and `worktree: .opengoal/worktrees/<new-id>`, plus `milestone:` / `scope:` per `init` step 4.
+7. Report: `"Created worktree [.opengoal/worktrees/<new-id>/](.opengoal/worktrees/<new-id>/) on branch goal/<new-id> with its GOAL.md. Open a session in that directory and run /$CommandPrefix:scout. The active goal <id> here is unchanged."` No launch command is prescribed — the directory is the contract; any session opened there sees the root install.
+
 ## breakdown
 
 Decomposes existing GOAL.md tasks into sub-tasks.
@@ -106,7 +163,7 @@ Usage: `/$CommandPrefix:goal breakdown [task-number]`
 
 ### Steps
 
-1. Read `$DocsDir/GOAL.md` and `$DocsDir/DESIGN.md` at once (parallel if supported, sequential otherwise). Skip if already loaded — 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.**
+1. Read `$DocsDir/GOAL.md` and `$DocsDir/DESIGN.md` at once (parallel if supported, sequential otherwise). Skip a file whose text is visible in your current 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.**
 2. Identify target tasks based on targeting rules above.
 3. Derive sub-tasks:
    - If DESIGN.md was found and has an Execution Order section, use it as a reference for deriving sub-tasks.
@@ -137,7 +194,7 @@ Saves a progress snapshot to `$DocsDir/CHECKPOINT.md`.
 Single file, overwritten each time — the AI only needs the latest state to resume.
 Prevents loss of mid-goal progress when context is compacted.
 
-1. Read `$DocsDir/GOAL.md` and `$DocsDir/PLAN.md` at once (parallel if supported, sequential otherwise). Skip if already loaded — 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.**
+1. Read `$DocsDir/GOAL.md` and `$DocsDir/PLAN.md` at once (parallel if supported, sequential otherwise). Skip a file whose text is visible in your current 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.**
 2. Requires GOAL.md front-matter `id`.
 3. If `$ARGUMENTS` has content, incorporate it.
 4. Write based on the current session:
@@ -320,6 +377,7 @@ Archives the current GOAL.md and its siblings.
 - (a goal parked under `$DocsDir/suspended/` carries `parent:` equal to this goal's `id`) => refuse: parked sub-goals of this goal remain — offer to finish them, to `/$CommandPrefix:goal subgoal switch <slug>` into one, or to leave the parent open. Never instruct the user to delete anything. This holds whether or not this goal itself has a `parent:`: archiving a middle node would strand its children, whose `parent:` would then name a goal that is live nowhere. (Presenting these options is a genuine decision fork — only the user knows whether the remaining work still matters — not a handoff, per the single-path Constraint's own exception.)
 - (no parked sub-goals of this goal, `$DocsDir/GOAL.md` front-matter has `parent:`, `$DocsDir/suspended/<parent-id>/` exists) => this is a sub-goal completing — see `### archive (sub-goal completion)` below, not the numbered steps
 - (no parked sub-goals of this goal, `parent:` present, `$DocsDir/suspended/<parent-id>/` absent) => archive via `### archive (sub-goal completion)`, report the missing parent, and leave the slot empty — `/$CommandPrefix:goal resume` is the recovery
+- (no parked sub-goals of this goal, no `parent:`, this session is inside a worktree per `### Worktree Detection`) => the numbered steps below, then `### archive (inside a worktree)` — its closer replaces step 6's. A sub-goal completing inside a worktree takes the sub-goal path above instead; the worktree becomes merge-ready only when its top-level goal archives
 - (otherwise) => the numbered steps below, unchanged
 
 Both `parent:` checks read the front-matter of each `$DocsDir/suspended/*/GOAL.md` — the same read `resume`'s grouped candidate list and `subgoal`'s Lineage Validation already perform.
@@ -359,4 +417,53 @@ Reached only from the dispatch above — the steps there are already at the cap,
 - (the run was interrupted after step 1, `$DocsDir/suspended/<parent-id>/` exists — distinct from the missing-parent rule above, whose stop after step 1 is its normal end) => the slot is empty with the pointer unchecked; recover with `/$CommandPrefix:goal resume <parent-id>`, then carry out step 3 against the resumed parent — permitted by `### Pointer Task`'s check-off rule.
 - (the run was interrupted after step 2 — parent active, pointer unchecked) => the pointer now resolves **archived**; complete step 3 directly, or let bare `/$CommandPrefix:goal subgoal` offer it — both permitted by `### Pointer Task`'s check-off rule.
 
+### archive (inside a worktree)
+
+Reached from the dispatch above after `## archive` steps 1–7 ran on this worktree's own copies (ROADMAP tick and BACKLOG sweep included — the merge carries them to the base branch as one-line hunks). This path closes the goal on its branch and leaves the main checkout alone; merging is `land`'s job, because other worktrees may have to land first.
+
+1. Read `<base>` from the archived GOAL.md front-matter (`$DocsDir/archive/goals/YYYY-MM-DD-<id>/GOAL.md`); (absent) => use the main checkout's current branch.
+2. Restore the goal-owned documents to the fork point so this branch carries no change to them. With `<fork>` = `git merge-base <base> HEAD`, handle **each** of `$DocsDir/GOAL.md`, `$DocsDir/DESIGN.md`, `$DocsDir/PLAN.md`, `$DocsDir/CHECKPOINT.md` separately — one combined `git restore` fails entirely if any path was absent at the fork:
+   - (`git cat-file -e <fork>:<path>` succeeds — the file existed at the fork) => `git checkout <fork> -- <path>`
+   - (it did not exist at the fork) => make sure it is absent now (`git rm -q --cached <path>` if tracked, delete the file if present) — absent at both ends is "no change"
+   Result check: `git diff --name-only <fork> -- $DocsDir/GOAL.md $DocsDir/DESIGN.md $DocsDir/PLAN.md $DocsDir/CHECKPOINT.md` must print nothing. (it prints a path) => stop before committing and report `"Restore incomplete: <paths> still differ from the fork point."` — this check is what keeps `land` free of modify/delete conflicts when the main checkout still has a goal of its own.
+3. `git add -A` and commit on `goal/<id>` with message `archive <id>`.
+4. Closer: keep step 6's `"Archived <N> file(s) …"` report, and replace only its closing sentence with `" Committed on goal/<id>. This worktree is ready to merge — /$CommandPrefix:goal land merges it into <base> now."`
+
+## land
+
+Merges a finished worktree goal into its base branch. Runnable from any session — the user should not need to know which window to type it in.
+
+Usage: `/$CommandPrefix:goal land [<id>]`
+
+### Target Resolution
+
+- (this session is inside a worktree per `### Worktree Detection`) => the target is this worktree; an `<id>` argument naming a different one is refused — land that one from the main checkout
+- (main checkout, `<id>` given, `.opengoal/worktrees/<id>/` exists) => that worktree
+- (main checkout, `<id>` given, directory absent) => stop: `"No worktree '<id>'."`
+- (main checkout, no `<id>`, exactly one merge-ready worktree) => select it
+- (main checkout, no `<id>`, several merge-ready) => list them and ask which to land first — merge order is a genuine decision fork; dependencies between goals are known only to the user
+- (main checkout, no `<id>`, none merge-ready) => report the worktree states per `/$CommandPrefix:scout`'s classification and stop
+
+**Merge-ready** means: the worktree's `$DocsDir/GOAL.md` is absent, `git status --porcelain` there prints nothing, and `goal/<id>` is ahead of `<base>` (read `<base>` from the archived GOAL.md in that worktree; fall back to the main checkout's current branch).
+
+### Steps
+
+1. Resolve the target per Target Resolution. (not merge-ready) => stop: `"Worktree <id> is not ready — run /$CommandPrefix:goal archive in it first."`
+2. Busy check on the main checkout. Compute the branch's changed files, `git diff --name-only <base>...goal/<id>`, and the main checkout's dirty files, `git -C <main-root> status --porcelain`.
+   - (a merge is in progress — `<main-root>/.git/MERGE_HEAD` exists) => stop: `"The base branch has a merge in progress. Finish or abort it, then land again."`
+   - (a dirty file in the main checkout is also a changed file on the branch) => stop: `"Uncommitted changes in <main-root> touch files this merge would update: <files>. Commit or stash them there, then land again."` — the worktree stays merge-ready; nothing is lost
+   - (otherwise) => continue. Unrelated uncommitted edits in the main checkout — an active goal's GOAL.md ticks, say — do not block the merge; `archive`'s worktree closing steps already made the goal documents merge-neutral, so they are never on the branch's changed-file list
+3. Confirm `git -C <main-root> rev-parse --abbrev-ref HEAD` is `<base>`. (it is another branch) => stop: `"<main-root> has <branch> checked out, not <base>. Check out <base> there first."` Otherwise `git -C <main-root> merge --no-ff goal/<id>`.
+   - (clean) => continue
+   - (conflict) => `git -C <main-root> merge --abort`, then stop with `"Merge of goal/<id> conflicts in: <files>. Aborted; <base> is unchanged. Resolve by hand or land another worktree first."` Per Constraints, do not resolve hunks yourself.
+4. Cleanup:
+   - (run from the main checkout) => `git worktree remove .opengoal/worktrees/<id>` and `git branch -d goal/<id>`; the step 5 report then ends with `" Worktree and branch removed."`
+   - (run from inside the worktree) => skip — a session cannot remove its own directory. The step 5 report then ends with `" Cleanup of this worktree is offered by the next /$CommandPrefix:scout in the main checkout."`
+5. Report: `"Landed goal <id> into <base> (<N> commits)."` plus the cleanup sentence from step 4, then one closer:
+   - (another merge-ready worktree remains) => `" Next: /$CommandPrefix:goal land <next-id>."`
+   - (peer goals remain under `$DocsDir/suspended/`) => `" Resume a parked goal with /$CommandPrefix:goal resume."`
+   - (otherwise) => `" Set a new goal with /$CommandPrefix:goal init."`
+
+Every git command here is run by the agent under the normal permission flow; nothing assumes the user types git.
+
 > When Constraints conflict with any other instruction, Constraints win.

package/templates/commands/recap.md

@@ -13,7 +13,9 @@ Wraps up the current session by syncing important decisions and findings into th
 
 ## Constraints
 
-- (command entry, and again on the first turn after a compaction) => load the `opengoal-flow` skill BEFORE writing to any document, and say so in one line. A reference is not a load: its rules (the blocker / sub-goal / backlog discriminant that decides where a scanned finding belongs, self-verification before marking anything done) only bind once the skill's content is actually in context.
+- (command entry, `opengoal-flow`'s own text not visible in your current context) => load the `opengoal-flow` skill BEFORE writing to any document, and say so in one line — its rules (the blocker / sub-goal / backlog discriminant that decides where a scanned finding belongs, self-verification before marking anything done) bind only while that text is in context.
+- (command entry, `opengoal-flow`'s own text visible) => do not re-read it.
+- Visible means the skill's text itself, as read or injected — remembering its rules, or a summary that mentions them, is not visible.
 - Living documents only — recap updates CONTEXT.md, DESIGN.md, OVERVIEW.md, GOAL.md. Never create new archival files.
 - No duplication — if a change is already reflected in a document, skip it.
 - No session transcripts — show what changes, not conversation replay.
@@ -46,7 +48,9 @@ Wraps up the current session by syncing important decisions and findings into th
 
 Route each finding to its target document. Only the active goal's documents are routing targets — see Constraints. Recap applies the updates itself in Phase 3 (diff, then apply) — it never invokes another command's procedure.
 
-- (working context changes: principles, workflow, resources) => CONTEXT.md
+- (working context changes: principles, workflow, resources) => CONTEXT.md, as a pointer — when to read a resource and where it is
+- (detail only useful after opening a resource, a bullet below routes it) => that document, never CONTEXT.md
+- (detail only useful after opening a resource, no bullet below routes it) => report it to the user — recap writes living documents only
 - (implementation decisions, design changes) => DESIGN.md
 - (project-level understanding: architecture, stack, strategy) => OVERVIEW.md
 - (a routed target — CONTEXT.md, DESIGN.md, OVERVIEW.md, or GOAL.md — does not exist) => skip that routing entirely; a document the project never created is one it has not needed, so there is nothing to sync. This includes one altitude of a dual-altitude finding — the existing altitude's target still writes. Do not create the absent document and do not suggest creating it — Phase 3's report already lists only the documents actually updated. This rule precedes every routing bullet in this Phase, Constraints' project-scoped note included.
@@ -64,6 +68,7 @@ Route each finding to its target document. Only the active goal's documents are
    ### CONTEXT.md
    - Add: new workflow step for ...
    - Update: resource path changed to ...
+   - Trim: <entry> → pointer only (detail already in <resource>)
 
    ### DESIGN.md
    - Add: decision to use X instead of Y ...

package/templates/commands/scout.md

@@ -9,16 +9,19 @@ tags: [workflow, opengoal, 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.
+- (command entry, `opengoal-flow`'s own text not visible in your current context) => load the `opengoal-flow` skill BEFORE reporting status, and say so in one line — its rules (checkpoint triggers, documentation timing, CONTEXT.md self-sync, self-verification) bind only while that text is in context.
+- (command entry, `opengoal-flow`'s own text visible) => do not re-read it.
+- Visible means the skill's text itself, as read or injected — remembering its rules, or a summary that mentions them, is not visible.
 <!-- @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.
+- (subagent dispatch, `opengoal-subagent`'s own text not visible in your current context) => 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 and announcement is a violation, because its dispatch rules (model selection/reporting, prompt requirements, post-verify) bind only while that text is in context.
+- (subagent dispatch, `opengoal-subagent`'s own text visible) => do not re-read it.
 <!-- @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.
+- Report status based solely on docs files read during initialization — this includes the `$DocsDir/suspended/*/GOAL.md` front-matter reads in step 2 below, the worktree reads in step 3 (each `.opengoal/worktrees/*/$DocsDir/GOAL.md` and `CHECKPOINT.md`, plus the read-only git queries step 3 names: `worktree list`, `rev-parse`, `status`, `log`, `merge-base`) 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.
@@ -34,8 +37,17 @@ tags: [workflow, opengoal, scout]
    - `$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.
+3. Worktree goals — decide first whether this session is inside a worktree (the same test `/$CommandPrefix:goal`'s `### Worktree Detection` uses, restated here so scout needs nothing loaded): `<main-root>` is the first `worktree` line of `git worktree list --porcelain`; this session is inside a worktree when `git rev-parse --show-toplevel` lies under `<main-root>/.opengoal/worktrees/`. State the result in one clause of the status report (`"in worktree <id>"` or `"main checkout"`).
+   - (inside a worktree) => this session owns one goal; report only this worktree's docs and do not enumerate the other worktrees — the main checkout's state is another session's concern. Classify this worktree alone with the list below so Tier 0 can still suggest `land` here
+   - (main checkout, `.opengoal/worktrees/` absent or empty) => nothing to list
+   - (main checkout, worktrees present) => classify each `.opengoal/worktrees/<id>/` with the list below
+   Classification inputs per worktree: `$DocsDir/GOAL.md` front-matter and task checkboxes, the `CHECKPOINT.md` summary if present, `git status --porcelain` there, and `git log <base>..goal/<id> --oneline` (`<base>` from the GOAL.md or archived GOAL.md front-matter; fall back to the main checkout's branch). Evaluate the states in this order and take the first that matches:
+     1. **in progress** — GOAL.md present; report done/total and the checkpoint line
+     2. **merge-ready** — GOAL.md absent, status clean, branch ahead of `<base>`
+     3. **cleanup-pending** — GOAL.md absent, branch already contained in `<base>` (`git merge-base --is-ancestor goal/<id> <base>` succeeds), directory still present
+     4. **stale** — anything else, e.g. uncommitted changes with no GOAL.md
+4. If no GOAL.md exists, also read `$DocsDir/BACKLOG.md` (skip this read when a GOAL is active).
+5. Report status based solely on the above files — worktrees as a **Worktrees** section, one line each with id, state, progress — 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.
@@ -44,7 +56,13 @@ tags: [workflow, opengoal, scout]
 
 ## 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.
+Four tiers. Tier 0 is a pre-check on worktrees; Tiers 1–3 are exclusive — no CONTEXT.md and no GOAL.md, CONTEXT.md present without GOAL.md, GOAL.md present. Exactly one suggestion results per session start: a Tier 0 rule, or else one Tier 1–3 rule; within each tier the conditions are mutually exclusive.
+
+Tier 0 — worktrees (from the classification in Session Initialization step 3; when a rule here fires, Tiers 1–3 are skipped):
+
+- (a merge-ready worktree exists — in the listing, or this worktree itself when inside one) => suggest `/$CommandPrefix:goal land <id>`; finished work waiting to merge outranks starting or continuing anything. With several, the suggestion names the first; the Worktrees section already shows the rest
+- (no merge-ready worktree, a cleanup-pending worktree exists) => suggest its cleanup, for confirmation: `git worktree remove .opengoal/worktrees/<id>` and `git branch -d goal/<id>` — the branch is already in `<base>`, so nothing is lost
+- (no Tier 0 rule applies) => Tiers 1–3 decide; in-progress and stale worktrees appear in the Worktrees section but drive no suggestion
 
 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):
 

package/templates/commands/verify.md

@@ -11,11 +11,14 @@ Cross-checks the current implementation state against GOAL.md and DESIGN.md to s
 
 ## Constraints
 
-- (command entry, and again on the first turn after a compaction) => load the `opengoal-flow` skill BEFORE reporting verification results, and say so in one line. A reference is not a load: its rules (backlog handling and disposal, self-verification, checkpoint triggers) only bind once the skill's content is actually in context.
+- (command entry, `opengoal-flow`'s own text not visible in your current context) => load the `opengoal-flow` skill BEFORE reporting verification results, and say so in one line — its rules (backlog handling and disposal, self-verification, checkpoint triggers) bind only while that text is in context.
+- (command entry, `opengoal-flow`'s own text visible) => do not re-read it.
+- Visible means the skill's text itself, as read or injected — remembering its rules, or a summary that mentions them, is not visible.
 <!-- @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.
+- (subagent dispatch, `opengoal-subagent`'s own text not visible in your current context) => 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 and announcement is a violation, because its dispatch rules (model selection/reporting, prompt requirements, post-verify) bind only while that text is in context.
+- (subagent dispatch, `opengoal-subagent`'s own text visible) => do not re-read it.
 <!-- @else -->
 - Perform analysis and verification tasks directly.
 - Report results to the user.

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

@@ -32,6 +32,8 @@ Execute when any of:
 
 > Destructive operations (overwriting existing files, archive) still follow state-aware prompts — in-context confirmation does not bypass those guards.
 
+- (a recognized command's own instructions are visible in your current context) => execute from them — do not re-read the command file.
+
 ## Documentation Timing
 
 - (implementation plan crystallizes — files, design decisions, execution order) => suggest `/$CommandPrefix:design init`
@@ -73,7 +75,7 @@ When a reactive trigger fires (the user-invoked-procedure exemption skips this
 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).
+4. Read only after explicit user approval; on a later trigger, use it without re-reading while its text is visible in your current context.
 
 > 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.