forge-workflow 0.1.0-beta.2 → 0.1.0-beta.4

package/skills/worktree/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: worktree
+description: >
+  Forge's worktree lifecycle. `forge worktree create <slug>` makes an isolated checkout
+  under `.worktrees/`, creates its branch (feat/<slug>), links a kernel issue (`--issue`),
+  and installs dependencies — all in one step; `forge worktree list`/`remove <slug>` manage
+  them; `forge clean` removes worktrees whose branches already merged (squash-aware) and
+  fast-forwards the default branch. Use when the user says "work on this in an isolated
+  branch/worktree", "spin up a worktree", "parallel work on another PR or issue", "clean up
+  merged worktrees", or "why did my worktree miss its dependencies". Footgun it prevents:
+  raw `git worktree add` only creates a branch — it skips the issue link and dep install —
+  so always use `forge worktree create`; and `forge clean` is cwd-scoped, run it from the
+  primary repo root, never inside a worktree. NOT for opening/pushing a PR or the branch
+  (ship), NOT for planning a feature (plan), NOT the stages that create a worktree as one
+  step — this is the worktree lifecycle itself.
+allowed-tools: Bash, Read, Grep, Glob
+terminal: true
+---
+
+Forge worktrees give a task its own isolated checkout so concurrent work never collides on `HEAD` or a shared branch. Use `forge worktree`, not raw `git worktree add` — the Forge command does the extra setup that a bare branch add skips.
+
+# Worktree lifecycle
+
+## When to use
+
+- "Work on this in an isolated branch / worktree", "spin up a worktree for this".
+- Parallel work: a second PR or issue you want to develop without disturbing the current checkout.
+- "Clean up the merged worktrees" — reclaim worktrees whose branches already landed.
+- Diagnosing "why did my new worktree miss its dependencies / node_modules".
+
+This skill is the **worktree lifecycle itself**. The `plan`/`ship` stages may create a worktree as one internal step, but managing worktrees directly — create, list, remove, clean — is this skill.
+
+## Create
+
+```bash
+forge worktree create <slug>
+```
+
+Creates the worktree at `.worktrees/<slug>` and, in one step:
+
+- creates its branch (default `feat/<slug>`),
+- links a kernel issue to the worktree when `--issue <id>` is given (records issue → worktree),
+- installs dependencies with the repo's detected package manager (bun/pnpm/yarn/npm).
+
+Flags:
+
+| Flag | Purpose |
+| --- | --- |
+| `--branch <name>` | Custom branch name (default `feat/<slug>`). |
+| `--base <ref>` | Base ref the new branch forks from (default the repo default branch, e.g. `origin/main`). |
+| `--issue <id>` | Kernel issue id to link this worktree to. |
+| `--work-folder <path>` | Repo-relative work-folder this issue owns (drops a `.forge-issue` marker). |
+
+The kernel issue store lives in the git common dir that every worktree shares, so a new worktree already sees the same kernel — no per-worktree issue-store bootstrap is needed.
+
+## The footgun this skill prevents
+
+**Never use raw `git worktree add`** for Forge work. It only creates a branch + checkout — it does **not** link the kernel issue and does **not** install dependencies. A worktree made that way is why deps end up missing. Always use `forge worktree create`.
+
+## List / remove
+
+```bash
+forge worktree list              # read the worktree registry from the kernel
+forge worktree remove <slug>     # git worktree remove for that slug
+```
+
+## Clean merged worktrees
+
+```bash
+forge clean                      # remove worktrees whose branches merged; FF the default branch
+forge clean --dry-run            # show what would be removed, change nothing
+```
+
+`forge clean` is **squash-aware** — it detects branches that merged via squash, not just fast-forward merges.
+
+### `forge clean` footguns
+
+- **cwd-scoped.** Run it from the **primary repo root**, never from inside a `.worktrees/<slug>` checkout. There is no default-branch guard, so a bare run from the wrong place can remove a clean checkout.
+- **Fast-forward the local default branch first** so squash-merge detection sees the merged state.
+- **Windows long paths.** `node_modules` inside a worktree can exceed the Windows path limit; if `git worktree remove --force` de-registers the worktree but the directory lingers, delete it with a PowerShell extended-path (`\\?\`) remove.
+
+## Adjacent skills
+
+- Opening or pushing a PR / the branch → `ship`.
+- Planning a feature (which may create a worktree as a step) → `plan`.
+- Watching an open PR toward merge → `shepherd`.
+- Everyday issue create/update/close → `issue-basics`.

package/skills/worktree/evals/evals.json

@@ -0,0 +1,38 @@
+[
+  {
+    "query": "Spin up an isolated worktree so I can work on this branch separately.",
+    "should_trigger": true
+  },
+  {
+    "query": "Create a worktree for this issue with its branch and dependencies installed.",
+    "should_trigger": true
+  },
+  {
+    "query": "I want to work on another PR in parallel without disturbing my current checkout.",
+    "should_trigger": true
+  },
+  {
+    "query": "Clean up all the merged worktrees and fast-forward main.",
+    "should_trigger": true
+  },
+  {
+    "query": "Why did my new worktree miss its node_modules dependencies?",
+    "should_trigger": true
+  },
+  {
+    "query": "Set up an isolated branch checkout under .worktrees for this task.",
+    "should_trigger": true
+  },
+  {
+    "query": "Open a pull request and push my feature branch.",
+    "should_trigger": false
+  },
+  {
+    "query": "Plan this new feature and break it into a task list.",
+    "should_trigger": false
+  },
+  {
+    "query": "Watch my PR and tell me why it isn't merging.",
+    "should_trigger": false
+  }
+]

package/skills/worktree/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "worktree",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 1013,
+      "body_lines": 70,
+      "score": 44
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 6,
+    "reachable": true,
+    "keyword_alignment": 1
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 83
+}

package/lib/adapters/beads-issue-adapter.js

@@ -1,127 +0,0 @@
-'use strict';
-
-const {
-  IssueAdapter,
-  decideIssueAuthority,
-  normalizeIssueStatus,
-} = require('../issue-adapter.js');
-
-class BeadsIssueAdapter extends IssueAdapter {
-  constructor(options = {}) {
-    super({
-      id: options.id || 'beads',
-      kind: 'issue',
-      name: options.name || 'Beads Issue Adapter',
-      version: options.version || '0.1.0',
-    });
-    this.runBeadsOperation = options.runBeadsOperation;
-  }
-
-  run(operation, args = [], context = {}) {
-    if (typeof this.runBeadsOperation !== 'function') {
-      throw new TypeError('runBeadsOperation is not configured on this adapter');
-    }
-
-    return this.runBeadsOperation(operation, args, context, context.deps || {});
-  }
-
-  list(args = [], context = {}) {
-    return this.run('list', args, context);
-  }
-
-  ready(args = [], context = {}) {
-    return this.run('ready', args, context);
-  }
-
-  read(args = [], context = {}) {
-    return this.run('show', args, context);
-  }
-
-  show(args = [], context = {}) {
-    return this.read(args, context);
-  }
-
-  create(args = [], context = {}) {
-    return this.run('create', args, context);
-  }
-
-  search(args = [], context = {}) {
-    return this.run('search', args, context);
-  }
-
-  stats(args = [], context = {}) {
-    return this.run('stats', args, context);
-  }
-
-  update(args = [], context = {}) {
-    return this.run('update', args, context);
-  }
-
-  close(args = [], context = {}) {
-    return this.run('close', args, context);
-  }
-
-  comment(args = [], context = {}) {
-    return this.run('comment', args, context);
-  }
-
-  depAdd(args = [], context = {}) {
-    return this.run('dep.add', args, context);
-  }
-
-  depRemove(args = [], context = {}) {
-    return this.run('dep.remove', args, context);
-  }
-
-  // De-bead parity: claim/release and the KAP-7/KAP-12 derived reads now route
-  // through the backend abstraction (the translations moved out of _issue.js). The
-  // beads layer maps claim -> `update <id> --claim`; release has no bd equivalent
-  // and returns the Kernel-only contract error (handled in runBeadsOperation).
-  claim(args = [], context = {}) {
-    return this.run('claim', args, context);
-  }
-
-  release(args = [], context = {}) {
-    return this.run('release', args, context);
-  }
-
-  blocked(args = [], context = {}) {
-    return this.run('blocked', args, context);
-  }
-
-  stale(args = [], context = {}) {
-    return this.run('stale', args, context);
-  }
-
-  orphans(args = [], context = {}) {
-    return this.run('orphans', args, context);
-  }
-
-  lint(args = [], context = {}) {
-    return this.run('lint', args, context);
-  }
-
-  // Lease ownership is Kernel-only; the beads layer returns the Kernel-only contract
-  // error (handled in runBeadsOperation), matching the release passthrough.
-  owns(args = [], context = {}) {
-    return this.run('owns', args, context);
-  }
-
-  // Active-lease listing is Kernel-only (kernel_claims); the beads layer returns the
-  // Kernel-only contract error (handled in runBeadsOperation), matching owns/release.
-  claims(args = [], context = {}) {
-    return this.run('claims', args, context);
-  }
-
-  mapStatus(status, context = {}) {
-    return normalizeIssueStatus(status, context);
-  }
-
-  decideAuthority(change = {}, context = {}) {
-    return decideIssueAuthority(change, context);
-  }
-}
-
-module.exports = {
-  BeadsIssueAdapter,
-};

package/lib/commands/board.js

@@ -1,64 +0,0 @@
-'use strict';
-
-const { readBeadsSnapshot } = require('../status/beads-snapshot');
-const { buildBoardJson, formatBoard } = require('../status/presenter');
-const { detectRepoContext } = require('./status');
-
-function hasJsonFlag(args = [], flags = {}) {
-	return flags.json === true || flags['--json'] === true || args.includes('--json');
-}
-
-function getFlagValue(args, dashedName, camelName) {
-	const inlineDashed = args.find(arg => typeof arg === 'string' && arg.startsWith(`${dashedName}=`));
-	if (inlineDashed) {
-		return inlineDashed.slice(dashedName.length + 1);
-	}
-	const inlineCamel = args.find(arg => typeof arg === 'string' && arg.startsWith(`${camelName}=`));
-	if (inlineCamel) {
-		return inlineCamel.slice(camelName.length + 1);
-	}
-	const dashedIndex = args.indexOf(dashedName);
-	if (dashedIndex !== -1 && dashedIndex + 1 < args.length) {
-		const candidate = args[dashedIndex + 1];
-		return typeof candidate === 'string' && candidate.startsWith('--') ? null : candidate;
-	}
-	const camelIndex = args.indexOf(camelName);
-	if (camelIndex !== -1 && camelIndex + 1 < args.length) {
-		const candidate = args[camelIndex + 1];
-		return typeof candidate === 'string' && candidate.startsWith('--') ? null : candidate;
-	}
-	return null;
-}
-
-async function handler(args = [], flags = {}, projectRoot = process.cwd()) {
-	const firstDefined = (...values) => values.find(value => value !== undefined && value !== null);
-	const context = detectRepoContext(projectRoot);
-	const snapshot = readBeadsSnapshot(projectRoot, {
-		now: firstDefined(flags.now, flags['--now'], getFlagValue(args, '--now', '--now')),
-		staleAfterDays: firstDefined(
-			flags.staleAfterDays,
-			flags['--stale-after-days'],
-			flags['--staleAfterDays'],
-			getFlagValue(args, '--stale-after-days', '--staleAfterDays')
-		),
-	});
-	const payload = { context, snapshot };
-	const output = hasJsonFlag(args, flags)
-		? JSON.stringify(buildBoardJson(payload), null, 2)
-		: formatBoard(payload);
-
-	return {
-		success: true,
-		context,
-		snapshot,
-		output,
-	};
-}
-
-module.exports = {
-	name: 'board',
-	description: 'Show a local team runtime board from kernel state',
-	handler,
-	getFlagValue,
-	hasJsonFlag,
-};

package/lib/status/beads-snapshot.js

@@ -1,145 +0,0 @@
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { secureExecFileSync } = require('../shell-utils.js');
-
-function getGitConfig(projectRoot, key) {
-	try {
-		return secureExecFileSync('git', ['config', key], {
-			encoding: 'utf8',
-			cwd: projectRoot,
-			stdio: ['pipe', 'pipe', 'pipe'],
-		}).trim();
-	} catch (_error) {
-		return '';
-	}
-}
-
-function getDeveloperIdentity(projectRoot) {
-	return {
-		email: getGitConfig(projectRoot, 'user.email'),
-		name: getGitConfig(projectRoot, 'user.name'),
-	};
-}
-
-function normalizeEmail(value) {
-	return typeof value === 'string' ? value.trim().toLowerCase() : '';
-}
-
-function readIssues(projectRoot) {
-	const issuesPath = path.join(projectRoot, '.beads', 'issues.jsonl');
-	if (!fs.existsSync(issuesPath)) {
-		return [];
-	}
-
-	const raw = fs.readFileSync(issuesPath, 'utf8');
-	const latestById = new Map();
-
-	for (const line of raw.split(/\r?\n/)) {
-		if (!line.trim()) {
-			continue;
-		}
-
-		try {
-			const issue = JSON.parse(line);
-			if (issue && issue.id) {
-				latestById.set(issue.id, issue);
-			}
-		} catch (_error) {
-			// Ignore malformed rows so one bad append does not break status.
-		}
-	}
-
-	return Array.from(latestById.values());
-}
-
-function isAssignedToDeveloper(issue, developer) {
-	if (!issue || !developer) {
-		return false;
-	}
-
-	if (issue.owner) {
-		const developerEmail = normalizeEmail(developer.email);
-		return developerEmail !== '' && normalizeEmail(issue.owner) === developerEmail;
-	}
-
-	return developer.name !== '' && issue.created_by === developer.name;
-}
-
-const DEFAULT_STALE_AFTER_DAYS = 14;
-
-function parseTimestampOrZero(value) {
-	if (!value) {
-		return 0;
-	}
-
-	const parsed = Date.parse(value);
-	return Number.isNaN(parsed) ? 0 : parsed;
-}
-
-function sortByUpdatedAtDesc(left, right) {
-	const leftTime = parseTimestampOrZero(left.updated_at);
-	const rightTime = parseTimestampOrZero(right.updated_at);
-	return rightTime - leftTime;
-}
-
-function hasUnresolvedDependencies(issue) {
-	return Number(issue.dependency_count || 0) > 0;
-}
-
-function isOpenIssue(issue) {
-	return issue.status === 'open' || issue.status === 'in_progress';
-}
-
-function isStale(issue, now, staleAfterDays) {
-	if (!isOpenIssue(issue)) {
-		return false;
-	}
-
-	const updatedAt = parseTimestampOrZero(issue.updated_at);
-	if (updatedAt === 0) {
-		return false;
-	}
-
-	const staleMs = staleAfterDays * 24 * 60 * 60 * 1000;
-	return now.getTime() - updatedAt >= staleMs;
-}
-
-function readBeadsSnapshot(projectRoot, options = {}) {
-	const developer = getDeveloperIdentity(projectRoot);
-	const issues = readIssues(projectRoot);
-	const parsedNow = options.now instanceof Date
-		? options.now
-		: (typeof options.now === 'string' ? new Date(options.now) : null);
-	const now = parsedNow instanceof Date && !Number.isNaN(parsedNow.getTime())
-		? parsedNow
-		: new Date();
-	const parsedStaleAfterDays = Number(options.staleAfterDays);
-	const staleAfterDays = Number.isFinite(parsedStaleAfterDays)
-		? parsedStaleAfterDays
-		: DEFAULT_STALE_AFTER_DAYS;
-
-	return {
-		developer,
-		issues,
-		active: issues.filter(issue => issue.status === 'in_progress').sort(sortByUpdatedAtDesc),
-		activeAssigned: issues.filter(issue => issue.status === 'in_progress' && isAssignedToDeveloper(issue, developer)),
-		ready: issues.filter(issue => issue.status === 'open' && !hasUnresolvedDependencies(issue)),
-		blocked: issues.filter(issue => isOpenIssue(issue) && hasUnresolvedDependencies(issue)).sort(sortByUpdatedAtDesc),
-		stale: issues.filter(issue => isStale(issue, now, staleAfterDays)).sort(sortByUpdatedAtDesc),
-		recentCompleted: issues.filter(issue => issue.status === 'closed').sort(sortByUpdatedAtDesc),
-		limits: [
-			'Uses local Beads issues.jsonl only.',
-			'Does not read GitHub review, CI, project, or sync freshness state.',
-		],
-	};
-}
-
-module.exports = {
-	getDeveloperIdentity,
-	isAssignedToDeveloper,
-	readBeadsSnapshot,
-	hasUnresolvedDependencies,
-	isStale,
-};