gsd-pi 2.20.0 → 2.22.0

package/src/resources/extensions/gsd/docs/claude-marketplace-import.md

@@ -0,0 +1,214 @@
+# Claude Marketplace Import
+
+This document describes the Claude marketplace import feature in GSD: what it reads, what it imports, what it persists, and what it does not translate into active GSD/Pi runtime behavior.
+
+---
+
+## What this feature does
+
+GSD can read Claude Code marketplace catalogs, inspect the plugins they reference, and import selected Claude skills into GSD/Pi while preserving Claude-style namespace identity.
+
+The interactive entry point is:
+
+```text
+/gsd prefs import-claude
+```
+
+You can also choose scope explicitly:
+
+```text
+/gsd prefs import-claude global
+/gsd prefs import-claude project
+```
+
+---
+
+## Claude Code model this feature follows
+
+Anthropic documents Claude marketplaces as sources users add with:
+
+```text
+/plugin marketplace add <github repo or local path>
+```
+
+A marketplace contains a catalog at:
+
+```text
+.claude-plugin/marketplace.json
+```
+
+Anthropic distinguishes between:
+
+- **Marketplace source** — where Claude fetches `marketplace.json`
+- **Plugin source** — where Claude fetches each plugin listed in that marketplace
+- **Installed plugin cache** — Claude copies installed plugin payloads into:
+
+```text
+~/.claude/plugins/cache
+```
+
+Anthropic also documents user-added marketplace sources under:
+
+```text
+~/.claude/plugins/marketplaces
+```
+
+GSD aligns its Claude import flow to that model.
+
+---
+
+## Where GSD looks
+
+For Claude plugin and marketplace material, GSD prefers Claude-managed locations first:
+
+1. `~/.claude/plugins/marketplaces`
+2. `~/.claude/plugins/cache`
+3. `~/.claude/plugins`
+
+After that, GSD still allows local clone-style convenience paths such as sibling repos or `~/repos/...` paths. Those fallbacks remain supported for developer workflows, but they are not the primary Claude storage model.
+
+---
+
+## What GSD imports
+
+### Imported into GSD/Pi settings
+
+- Claude skills discovered directly from configured skill roots
+- Marketplace-derived skills
+
+Imported marketplace skills preserve canonical namespace identity, for example:
+
+```text
+python3-development:stinkysnake
+scientific-method:experiment-protocol
+```
+
+### Discovered, modeled, and validated
+
+- Marketplace-derived agents
+
+### Discovered but not translated into active Pi-native runtime behavior
+
+- hooks
+- MCP server definitions
+- LSP server definitions
+- other plugin metadata that does not currently map directly into active GSD/Pi runtime surfaces
+
+---
+
+## Import flow
+
+The import flow does the following:
+
+1. discover Claude skills and marketplace/plugin roots
+2. identify marketplace roots by checking for `.claude-plugin/marketplace.json`
+3. inspect discovered plugins and inventory their components
+4. let you select components to import
+5. validate the selection for canonical conflicts and ambiguity
+6. persist imported resources into GSD/Pi settings
+
+---
+
+## Namespace behavior
+
+GSD preserves Claude plugin namespace semantics rather than flattening plugin components into anonymous global names.
+
+### Canonical references
+
+Canonical references remain available for imported components:
+
+- skills: `plugin-name:skill-name`
+- agents: `plugin-name:agent-name`
+
+### Shorthand
+
+GSD supports shorthand lookup when it is unambiguous.
+
+### Local-first resolution
+
+When a namespaced component refers to another component by bare name, GSD tries the same plugin namespace first before broader lookup.
+
+---
+
+## Important safeguard: marketplace agent directories are not stored as package sources
+
+Claude plugin agent directories are markdown agent-definition directories, for example:
+
+```text
+.../plugins/python3-development/agents
+```
+
+GSD does **not** persist imported marketplace agent directories into:
+
+```json
+settings.packages
+```
+
+This is intentional.
+
+### Why
+
+Persisting an `.../agents` directory into `settings.packages` can cause Pi startup to treat that directory as an extension/package root. In real host validation, that produced extension loader failures such as:
+
+```text
+Cannot find module '.../agents'
+```
+
+GSD now avoids writing those entries.
+
+---
+
+## Settings effects
+
+### Skills
+
+Imported skills are persisted into Pi skill settings. Depending on the selection path, they may also be added to GSD preferences.
+
+### Marketplace agents
+
+Marketplace agents remain part of the import model and validation surface, but their `agents/` directories are not persisted as package roots.
+
+---
+
+## Diagnostics
+
+GSD distinguishes between:
+
+- **canonical conflicts** — hard errors
+- **shorthand overlaps** — warnings when canonical names remain distinct
+- **alias conflicts** — diagnostics for alias collisions or shadowing
+
+This allows imported marketplace content to be validated without reporting valid overlap as fatal breakage.
+
+---
+
+## Verification status of this feature
+
+This feature has been verified in three ways:
+
+1. **Contract/unit tests** for parsing, namespacing, resolution, diagnostics, and import behavior
+2. **Portable integration-style tests** using local or cloned marketplace fixtures
+3. **Real host validation** against the installed `gsd` binary and actual Claude-managed directories on the host machine
+
+Real host validation included:
+
+- clean startup of the installed `gsd` binary after fixing stale bad settings
+- successful invocation of an imported skill (`/stinkysnake`)
+- successful execution of `/gsd prefs import-claude global`
+- verification that imported marketplace agent directories were **not** reintroduced into `settings.packages`
+
+---
+
+## Current limitations
+
+- GSD does not yet translate every Claude plugin component type into active Pi-native runtime behavior
+- marketplace-derived agents are not persisted as package roots, by design
+- clone-style local fallbacks still exist for developer convenience, even though Claude-managed marketplace/plugin locations are preferred first
+
+---
+
+## References
+
+- Anthropic: Claude Code settings
+- Anthropic: Create and distribute a plugin marketplace
+- Anthropic: Plugins and plugin reference

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -10,6 +10,7 @@ Full documentation for `~/.gsd/preferences.md` (global) and `.gsd/preferences.md
 - Prefer explicit skill names or absolute paths.
 - Use absolute paths for personal/local skills when you want zero ambiguity.
 - These preferences guide which skills GSD should load and follow; they do not override higher-priority instructions in the current conversation.
+- For Claude marketplace/plugin import behavior, see `~/.gsd/agent/extensions/gsd/docs/claude-marketplace-import.md`.
 
 ---
 
@@ -123,7 +124,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `commit_type`: string — override the conventional commit type prefix. Must be one of: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `build`, `style`. Default: inferred from diff content.
   - `main_branch`: string — the primary branch name for new git repos (e.g., `"main"`, `"master"`, `"trunk"`). Also used by `getMainBranch()` as the preferred branch when auto-detection is ambiguous. Default: `"main"`.
   - `merge_strategy`: `"squash"` or `"merge"` — controls how worktree branches are merged back. `"squash"` combines all commits into one; `"merge"` preserves individual commits. Default: `"squash"`.
-  - `isolation`: `"worktree"` or `"branch"` — controls auto-mode git isolation strategy. `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root (useful for submodule-heavy repos). Default: `"worktree"`.
+  - `isolation`: `"worktree"`, `"branch"`, or `"none"` — controls auto-mode git isolation strategy. `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root but creates a milestone branch (useful for submodule-heavy repos); `"none"` works directly on the current branch with no worktree or milestone branch (ideal for step-mode with hot reloads). Default: `"worktree"`.
   - `commit_docs`: boolean — when `false`, prevents GSD from committing `.gsd/` planning artifacts to git. The `.gsd/` folder is added to `.gitignore` and kept local-only. Useful for teams where only some members use GSD, or when company policy requires a clean repository. Default: `true`.
   - `worktree_post_create`: string — script to run after a worktree is created (both auto-mode and manual `/worktree`). Receives `SOURCE_DIR` and `WORKTREE_DIR` as environment variables. Can be absolute or relative to project root. Runs with 30-second timeout. Failure is non-fatal (logged as warning). Default: none.
 

package/src/resources/extensions/gsd/doctor.ts

@@ -5,7 +5,7 @@ import { loadFile, parsePlan, parseRoadmap, parseSummary, saveFile, parseTaskPla
 import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile } from "./paths.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { loadEffectiveGSDPreferences, type GSDPreferences } from "./preferences.js";
-import { listWorktrees } from "./worktree-manager.js";
+import { listWorktrees, resolveGitDir } from "./worktree-manager.js";
 import { abortAndReset } from "./git-self-heal.js";
 import { RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
 import { nativeIsRepo, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached } from "./native-git-bridge.js";
@@ -474,15 +474,19 @@ async function checkGitHealth(
   issues: DoctorIssue[],
   fixesApplied: string[],
   shouldFix: (code: DoctorIssueCode) => boolean,
+  isolationMode: "none" | "worktree" | "branch" = "worktree",
 ): Promise<void> {
   // Degrade gracefully if not a git repo
   if (!nativeIsRepo(basePath)) {
     return; // Not a git repo — skip all git health checks
   }
 
-  const gitDir = join(basePath, ".git");
+  const gitDir = resolveGitDir(basePath);
 
-  // ── Orphaned auto-worktrees ──────────────────────────────────────────
+  // ── Orphaned auto-worktrees & Stale milestone branches ────────────────
+  // These checks only apply in worktree/branch modes — skip in none mode
+  // where no milestone worktrees or branches are created.
+  if (isolationMode !== "none") {
   try {
     const worktrees = listWorktrees(basePath);
     const milestoneWorktrees = worktrees.filter(wt => wt.branch.startsWith("milestone/"));
@@ -576,6 +580,7 @@ async function checkGitHealth(
   } catch {
     // listWorktrees or deriveState failed — skip worktree/branch checks
   }
+  } // end isolationMode !== "none"
 
   // ── Corrupt merge state ────────────────────────────────────────────────
   try {
@@ -976,7 +981,10 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   }
 
   // Git health checks (orphaned worktrees, stale branches, corrupt merge state, tracked runtime files)
-  await checkGitHealth(basePath, issues, fixesApplied, shouldFix);
+  const isolationMode: "none" | "worktree" | "branch" =
+    prefs?.preferences?.git?.isolation === "none" ? "none" :
+    prefs?.preferences?.git?.isolation === "branch" ? "branch" : "worktree";
+  await checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode);
 
   // Runtime health checks (crash locks, completed-units, hook state, activity logs, STATE.md, gitignore)
   await checkRuntimeHealth(basePath, issues, fixesApplied, shouldFix);

package/src/resources/extensions/gsd/file-watcher.ts

@@ -0,0 +1,97 @@
+import type { FSWatcher } from "chokidar";
+import type { EventBus } from "@gsd/pi-coding-agent";
+import { relative } from "node:path";
+
+let watcher: FSWatcher | null = null;
+
+const EVENT_MAP: Record<string, string> = {
+	"settings.json": "settings-changed",
+	"auth.json": "auth-changed",
+	"models.json": "models-changed",
+};
+
+const EXTENSIONS_DIR = "extensions";
+
+const IGNORED_PATTERNS = [
+	"**/sessions/**",
+	"**/*.tmp",
+	"**/*.swp",
+	"**/*~",
+	"**/.DS_Store",
+];
+
+const DEBOUNCE_MS = 300;
+
+/**
+ * Start watching `agentDir` (e.g. `~/.gsd/agent/`) for config changes.
+ * Emits events on the supplied EventBus when watched files are modified.
+ */
+export async function startFileWatcher(
+	agentDir: string,
+	eventBus: EventBus,
+): Promise<void> {
+	if (watcher) {
+		await watcher.close();
+	}
+
+	const { watch } = await import("chokidar");
+
+	const pending = new Map<string, ReturnType<typeof setTimeout>>();
+
+	function debounceEmit(event: string): void {
+		const existing = pending.get(event);
+		if (existing) clearTimeout(existing);
+		pending.set(
+			event,
+			setTimeout(() => {
+				pending.delete(event);
+				eventBus.emit(event, { timestamp: Date.now() });
+			}, DEBOUNCE_MS),
+		);
+	}
+
+	function resolveEvent(filePath: string): string | null {
+		const rel = relative(agentDir, filePath);
+		if (rel.startsWith("..")) return null;
+
+		// Check direct file matches
+		for (const [file, event] of Object.entries(EVENT_MAP)) {
+			if (rel === file) return event;
+		}
+
+		// Check extensions directory
+		if (rel.startsWith(EXTENSIONS_DIR + "/") || rel === EXTENSIONS_DIR) {
+			return "extensions-changed";
+		}
+
+		return null;
+	}
+
+	watcher = watch(agentDir, {
+		ignoreInitial: true,
+		depth: 2,
+		ignored: IGNORED_PATTERNS,
+	});
+
+	for (const eventType of ["add", "change", "unlink"] as const) {
+		watcher.on(eventType, (filePath: string) => {
+			const event = resolveEvent(filePath);
+			if (event) debounceEmit(event);
+		});
+	}
+
+	// Wait for watcher to be ready
+	await new Promise<void>((resolve) => {
+		watcher!.on("ready", resolve);
+	});
+}
+
+/**
+ * Stop the file watcher and clean up resources.
+ */
+export async function stopFileWatcher(): Promise<void> {
+	if (watcher) {
+		await watcher.close();
+		watcher = null;
+	}
+}

package/src/resources/extensions/gsd/files.ts

@@ -436,7 +436,7 @@ function _parsePlanImpl(content: string): SlicePlan {
     let currentTask: TaskPlanEntry | null = null;
 
     for (const line of taskLines) {
-      const cbMatch = line.match(/^-\s+\[([ xX])\]\s+\*\*(\w+):\s+(.+?)\*\*\s*(.*)/);
+      const cbMatch = line.match(/^-\s+\[([ xX])\]\s+\*\*([\w.]+):\s+(.+?)\*\*\s*(.*)/);
       if (cbMatch) {
         if (currentTask) tasks.push(currentTask);