@opellen/opengoal 1.0.7 → 1.1.0-rc.2

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.7",
+  "version": "1.1.0-rc.2",
   "description": "Goal-centric AI harness. Plain markdown, zero runtime — nothing runs but your agent.",
   "type": "module",
   "license": "MIT",

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]
 ---
@@ -15,10 +15,12 @@ Manages `$DocsDir/GOAL.md`.
 - (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.
 
@@ -28,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
@@ -45,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
@@ -60,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
@@ -77,6 +82,11 @@ 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
+branch: goal/<goal-slug>   # worktree goals only — the worktree's own branch
 ---
 ```
 
@@ -92,6 +102,55 @@ 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**.
+- A worktree goal's branch is the `branch:` field of its GOAL.md (archived GOAL.md once archived); when the field is absent, assume `goal/<id>`.
+
+### 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: run `git status --porcelain -- $DocsDir` on the main checkout. (it prints files) => list them and say: `"These uncommitted docs will not be visible in the new worktree until they are committed here and merged in. Continue?"` — a genuine fork, since only the user knows whether the new goal needs them. (continue) => go on; (no) => stop with the active goal unchanged. A worktree is a checkout of HEAD; the new GOAL.md is written fresh, so the gap is limited to shared docs such as CONTEXT.md or ROADMAP.md.
+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>`, `worktree: .opengoal/worktrees/<new-id>` and `branch: goal/<new-id>`, plus `milestone:` / `scope:` per `init` step 4.
+7. Move this session into the worktree, then report. The user should never have to open another window to reach the goal they just created.
+   - (the platform can move a running session's working directory — Claude Code: the `EnterWorktree` tool with `path` set to the worktree's absolute path (choosing option 1 is the explicit worktree request that tool requires); Codex CLI: `/cd <absolute path>`) => do it. This session is now the goal session; the main checkout and its active goal are untouched. Report: `"Created worktree [.opengoal/worktrees/<new-id>/](.opengoal/worktrees/<new-id>/) on branch goal/<new-id>. This session now works in it — run /$CommandPrefix:scout to continue. Goal <id> in the main checkout is unchanged."`
+   - (the platform cannot move a running session — Gemini CLI has no such command; in Antigravity, prefer its own "New Worktree" conversation mode over this procedure) => 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. Goal <id> here is unchanged."` The directory is the contract; a session opened there sees the root install through ancestor lookup.
+
 ## breakdown
 
 Decomposes existing GOAL.md tasks into sub-tasks.
@@ -322,6 +381,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.
@@ -361,4 +421,54 @@ 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, the platform can move the session back to the main checkout — Claude Code: `ExitWorktree` with `action: keep`; Codex CLI: `/cd <main-root>`) => leave the worktree first, then remove the worktree and branch exactly as from the main checkout; the step 5 report then ends with `" Worktree and branch removed; this session is back in the main checkout."`
+   - (run from inside the worktree, the platform cannot move the session) => 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/scout.md

@@ -21,7 +21,7 @@ tags: [workflow, opengoal, scout]
 - 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.
@@ -37,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>..<branch> --oneline` (`<base>` and `<branch>` from the GOAL.md or archived GOAL.md front-matter; fall back to the main checkout's branch and `goal/<id>`). 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.
@@ -47,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):