dev-loops 0.5.0 → 0.7.1

package/agents/dev-loop.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "dev-loop"
 description: "Use as the single public workflow entrypoint. Route from canonical current state to the deterministic internal strategy, preferring GitHub-first paths and only using local phase implementation when explicitly requested. Keywords: dev-loop, public entrypoint, route workflow, continue dev loop."
-tools: [read, search, execute, bash, agent, todo, subagent]
+tools: read, search, execute, bash, agent, todo, subagent
 argument-hint: "A dev-loop intent such as issue number/URL, PR number/URL, or a request to continue/inspect current state."
 systemPromptMode: append
 inheritProjectContext: true
@@ -23,10 +23,18 @@ The envelope is the primary handoff artifact — it is derived from resolver out
 - `nextAction` — the bounded task to execute
 - `stopRules` — stop boundaries that must not be crossed without authorization
 - `acceptance` — self-validation criteria for declaring completion
+- `sanctionedCommands` — the operation → wrapper command map (reads/edits/lifecycle), plus the forbidden and orchestrator-owned lists. Carried by DEFAULT on every build so you never re-derive which wrapper performs a GitHub/loop operation. Do NOT restate the map here — the single source of truth is `scripts/loop/sanctioned-commands.mjs`, surfaced verbatim in the envelope.
 
 **Construction sequence:**
 <!-- pi-only -->
-**CLI invocation (`<dev-loops-package-root>`):** dev-loop CLI commands are invoked as `node <dev-loops-package-root>/cli/index.mjs <verb...>` using the package-local CLI rather than `npx`, so they resolve unambiguously from the installed package without a global install. Resolve `<dev-loops-package-root>` from this agent's own installed path: this agent is installed at `<package-root>/.pi/agents/dev-loop.agent.md`, so the package root is `../..` from this agent's directory (`agents` → `.pi` → package root). (The `dev-loop` skill resolves it analogously from its own installed path.)
+**CLI invocation (`<dev-loops-package-root>`):** dev-loop CLI commands are invoked as `node <dev-loops-package-root>/cli/index.mjs <verb...>` using the package-local CLI rather than `npx`, so they resolve unambiguously from the installed package without a global install. Resolve `<dev-loops-package-root>` via the first of these **bounded** candidates whose `cli/index.mjs` exists — never assume a single fixed layout (this agent may be installed user-level at `~/.agents/`, where the old `../..` package-relative guess resolves to `~`, not the package):
+
+1. **Node module resolution** (best-effort first try): `node -e "try{const p=require('node:path');console.log(p.resolve(p.dirname(require.resolve('dev-loops/cli/index.mjs')),'..'))}catch{process.exit(1)}"` — resolves the package root when `dev-loops` is reachable from Node's module search path (notably under `~/.pi/agent/npm`); this is cwd-dependent and commonly misses from a target-repo cwd, so the probe is wrapped in try/catch (no stack trace, exits non-zero on miss) — treat a non-zero exit as "probe missed, try the next candidate", not a hard failure.
+2. **Pi user-agent npm root** (reliable for user-level installs): `~/.pi/agent/npm/node_modules/dev-loops`.
+3. **Package-relative (legacy):** `../..` from this agent's own directory (the original package-local install layout).
+4. **Global npm root:** `$(npm root -g)/dev-loops`.
+
+NEVER fall back to `find /` or any unbounded filesystem walk to locate the CLI — it stalls and trips the needs-attention timeout. If every bounded candidate fails, stop and ask the orchestrator/operator for the dev-loops package root rather than searching. (The `dev-loop` skill resolves it analogously.)
 <!-- /pi-only -->
 
 1. Run the deterministic startup resolver to produce the authoritative state bundle: `node <dev-loops-package-root>/cli/index.mjs loop startup --issue <n>` for issues, or `node <dev-loops-package-root>/cli/index.mjs loop startup --pr <n>` for PRs.
@@ -64,7 +72,7 @@ If local facts, GitHub facts, and helper/state-machine output do not agree well
 ## Subagent delegation
 
 <!-- pi-only -->
-This agent has `tools: [subagent]` and `maxSubagentDepth: 3` to allow orchestrating parallel review, chains, and staged fix passes.
+This agent's frontmatter `tools:` comma-token scalar includes `subagent` (single-line comma form, no brackets — see #1111) and it sets `maxSubagentDepth: 3` to allow orchestrating parallel review, chains, and staged fix passes.
 <!-- /pi-only -->
 
 All delegation must originate from the handoff envelope: the envelope's `nextAction`, `requiredReads`, `stopRules`, and `acceptance` define the bounded task. The envelope is passed to child subagents as their primary handoff artifact.

package/agents/developer.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "developer"
 description: "Use for direct product implementation in this repository: focused code changes, refactors, tests, bug fixes, and feature work within an already-scoped task. Keywords: implement feature, write code, refactor module, add tests, fix bug, update source."
-tools: [read, search, execute, bash, edit, write]
+tools: read, search, execute, bash, edit, write
 argument-hint: "Focused implementation task, relevant files, success criteria, and required verification."
 systemPromptMode: append
 inheritProjectContext: true

package/agents/docs.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "docs"
 description: "Use for README updates, plan docs, architecture notes, agent docs, migration notes, narrow documentation changes that must stay aligned with implementation work, and documentation-correctness review for the current change. Keywords: docs, README, plans, documentation, agent docs, rollout notes, changelog-style summary, docs review."
-tools: [read, search, execute, bash, edit, write]
+tools: read, search, execute, bash, edit, write
 argument-hint: "Documentation task or documentation-correctness review, affected files, source changes to reflect, and required level of detail."
 systemPromptMode: append
 inheritProjectContext: true

package/agents/fixer.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "fixer"
 description: "Use for addressing active pull request review comments and threads: inspect unresolved feedback, make the narrow fix, verify it, push the fixing commit, reply with the resolving commit, and resolve the thread. Keywords: fixer, PR comments, address review feedback, resolve review threads, push fix commit."
-tools: [read, search, execute, bash, edit, write]
+tools: read, search, execute, bash, edit, write
 argument-hint: "Review-fix task, PR number or branch, target reviewer/thread/file, and required verification."
 systemPromptMode: append
 inheritProjectContext: true

package/agents/quality.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "quality"
 description: "Use for build systems, test runners, type-checking, linting, package scripts, GitHub Actions workflows, caches, release verification, and quality gates. Keywords: CI, workflow, GitHub Actions, build, test, cache, typecheck, package scripts, branch protection."
-tools: [read, search, execute, bash, edit, write]
+tools: read, search, execute, bash, edit, write
 argument-hint: "Quality or CI task, relevant workflows/config files, required checks, and verification expectations."
 systemPromptMode: append
 inheritProjectContext: true

package/agents/refiner.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "refiner"
 description: "Use for refining one approved implementation phase at a time into a complete, testable plan with acceptance criteria, definition of done, risks, non-goals, unresolved questions, and RFC escalation notes. Keywords: refiner, phase refinement, acceptance criteria, definition of done, RFC escalation, merged plan."
-tools: [read, search, execute, bash, edit, write]
+tools: read, search, execute, bash, edit, write
 argument-hint: "Active phase doc or rough plan, phase boundary, known constraints, and any prior planning artifacts to refine."
 systemPromptMode: append
 inheritProjectContext: true

package/agents/review.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "review"
 description: "Use for pull request review from a product and engineering perspective: check the implementation against the PR description, relevant plan, acceptance criteria, definition of done, non-goals, coding best practices, security expectations, and merge readiness. Keywords: review, PR review, acceptance criteria review, DoD review, security review, plan compliance."
-tools: [read, search, execute, bash, edit, write]
+tools: read, search, execute, bash, edit, write
 argument-hint: "PR number or branch, relevant plan files, and any specific review focus areas or constraints."
 systemPromptMode: append
 inheritProjectContext: true
@@ -33,7 +33,8 @@ This agent has two modes. The default mode is the full-PR review described in th
 
 You are in scoped angle-review mode when the invocation supplies a single review `<angle>` plus a gate-context artifact path (`tmp/gate-context/<repo-slug>/pr-<N>/<gate>-<headSha>.json`, written by `scripts/github/write-gate-context.mjs`). Review like an external code reviewer hunting real bugs, not a process auditor: your job is to find concrete defects in the changed code and its call paths, not to remark that "there is no test" or that a doc section is thin. In that mode:
 
-- **Fresh-context guard (mandatory):** run `node scripts/github/verify-fresh-review-context.mjs --scope <angle>` at startup. If it reports `fresh: false` (exit 1) or any error, refuse to proceed and report contamination — do not review on inherited context. "Fresh" here means your context is the **neutral builder artifact + your angle**, and explicitly NOT the main agent's conversation/state or a prior reviewer session's state. The injected neutral bundle is the INTENDED seed (allowed); main-agent or cross-session state bleed still fails closed.
+- **No worktree isolation (mandatory):** you review in the PR's actual worktree/head — the same checkout the gate-context preamble ran in — never a fresh isolated worktree. You are read-only and never mutate files, so isolation buys nothing; a fresh worktree would also be checked out from `main` (not the PR head) and would lack the gitignored, worktree-local gate-context bundle below, so you'd silently review the wrong stale tree (#1135).
+- **Fresh-context guard (mandatory):** run `node scripts/github/verify-fresh-review-context.mjs --scope <angle> --context-path <gate-context-artifact-path>` at startup. If it reports `fresh: false` (exit 1) or any error — including a missing gate-context artifact (`gateContextPresent: false`), which is the fail-closed signal that you're not in the right worktree/head — refuse to proceed and report the failure; do not review on inherited context or without seeded context. "Fresh" here means your context is the **neutral builder artifact + your angle**, and explicitly NOT the main agent's conversation/state or a prior reviewer session's state. The injected neutral bundle is the INTENDED seed (allowed); main-agent or cross-session state bleed still fails closed.
 - **Use the PROVIDED neutral bundle as your base; do NOT re-derive it from scratch:** the gate-context artifact carries the diff (`scope.diffPath`) and a deterministic, neutral adjacent-code bundle in `adjacentCode` (each changed file plus its 1-hop import in/out-edges, with a `stripped`/`truncated`/`missing` manifest). Start from this bundle — it is the build-once, work-deduped seed shared verbatim across all reviewers. Only widen (load more files) per-angle when the bundle genuinely lacks something your angle needs; do not re-build the whole diff/adjacent-code graph yourself.
 - **Single-angle scope:** review ONLY the supplied angle's concern. Read the gate-context artifact for the resolved angle set, change scope (branch, head SHA, touched files), acceptance-criteria pointer, and validation posture. Do not review other angles; the fan-in pass consolidates across angles.
 - **Read the FULL diff, not just hunks:** the gate-context artifact records `scope.diffPath` (a repo-relative path to the complete captured diff) and `scope.changedFiles` (full repo-relative paths). Read the entire diff from `scope.diffPath`; if it is `null` or missing, reconstruct it yourself with `git diff` against the change's base (e.g. `git diff origin/main...HEAD` or the branch/head SHA in `scope`). Do not review off a partial or summarized hunk list — you must see every changed line for your angle.

package/cli/index.mjs

@@ -17,6 +17,34 @@ import { createPiAdapter } from "@dev-loops/core/harness";
 
 const REPO_ROOT = fileURLToPath(new URL("..", import.meta.url));
 
+// `project` is an alias for `queue` minus the run driver — derived, not duplicated.
+const QUEUE_ROUTES = {
+  run:            "scripts/loop/run-queue.mjs",
+  list:    "scripts/projects/list-queue-items.mjs",
+  add:     "scripts/projects/add-queue-item.mjs",
+  move:    "scripts/projects/move-queue-item.mjs",
+  reorder: "scripts/projects/reorder-queue-item.mjs",
+  "archive-done": "scripts/projects/archive-done-items.mjs",
+  "sync-status": "scripts/projects/sync-item-status.mjs",
+  ensure:  "scripts/projects/ensure-queue-board.mjs",
+  "resolve-active": "scripts/projects/resolve-active-board-item.mjs",
+  reconcile: "scripts/projects/reconcile-queue.mjs",
+};
+const { run: _queueRunRoute, ...PROJECT_ROUTES } = QUEUE_ROUTES;
+
+const QUEUE_DESCRIPTIONS = {
+  run: "Run queue driver",
+  list: "List queue board items",
+  add: "Add issue/PR to queue board",
+  move: "Move queue item between Status columns",
+  reorder: "Reorder items (move-to-top/move-after/order, --dry-run)",
+  "archive-done": "Archive closed Done items older than a duration",
+  "sync-status": "Sync a queued issue/PR's board Status column (best-effort)",
+  ensure: "Create/repair queue board bootstrap surface",
+  reconcile: "Reconcile board Status columns from live GitHub state (idempotent)",
+};
+const { run: _queueRunDescription, ...PROJECT_DESCRIPTIONS } = QUEUE_DESCRIPTIONS;
+
 const SUBCOMMAND_ROUTES = {
   gate: {
     "upsert-verdict":     "scripts/github/upsert-checkpoint-verdict.mjs",
@@ -50,25 +78,8 @@ const SUBCOMMAND_ROUTES = {
     "ready-for-review": "scripts/github/ready-for-review.mjs",
     "reconcile-draft":  "scripts/github/reconcile-draft-gate.mjs",
   },
-  project: {
-    list:    "scripts/projects/list-queue-items.mjs",
-    add:     "scripts/projects/add-queue-item.mjs",
-    move:    "scripts/projects/move-queue-item.mjs",
-    reorder: "scripts/projects/reorder-queue-item.mjs",
-    "archive-done": "scripts/projects/archive-done-items.mjs",
-    "sync-status": "scripts/projects/sync-item-status.mjs",
-    ensure:  "scripts/projects/ensure-queue-board.mjs",
-  },
-  queue: {
-    run:            "scripts/loop/run-queue.mjs",
-    list:    "scripts/projects/list-queue-items.mjs",
-    add:     "scripts/projects/add-queue-item.mjs",
-    move:    "scripts/projects/move-queue-item.mjs",
-    reorder: "scripts/projects/reorder-queue-item.mjs",
-    "archive-done": "scripts/projects/archive-done-items.mjs",
-    "sync-status": "scripts/projects/sync-item-status.mjs",
-    ensure:  "scripts/projects/ensure-queue-board.mjs",
-  },
+  queue: QUEUE_ROUTES,
+  project: PROJECT_ROUTES,
   inspect: {
     run:    "scripts/loop/inspect-run.mjs",
     viewer: "scripts/loop/inspect-run-viewer.mjs",
@@ -141,25 +152,8 @@ const SUBCOMMAND_DESCRIPTIONS = {
     "ready-for-review": "Mark PR ready for review",
     "reconcile-draft": "Reconcile non-draft PR",
   },
-  project: {
-    list: "List queue board items",
-    add: "Add issue/PR to queue board",
-    move: "Move queue item between Status columns",
-    reorder: "Reorder items (move-to-top/move-after/order, --dry-run)",
-    "archive-done": "Archive closed Done items older than a duration",
-    "sync-status": "Sync a queued issue/PR's board Status column (best-effort)",
-    ensure: "Create/repair queue board bootstrap surface",
-  },
-  queue: {
-    run: "Run queue driver",
-    list: "List queue board items",
-    add: "Add issue/PR to queue board",
-    move: "Move queue item between Status columns",
-    reorder: "Reorder items (move-to-top/move-after/order, --dry-run)",
-    "archive-done": "Archive closed Done items older than a duration",
-    "sync-status": "Sync a queued issue/PR's board Status column (best-effort)",
-    ensure: "Create/repair queue board bootstrap surface",
-  },
+  queue: QUEUE_DESCRIPTIONS,
+  project: PROJECT_DESCRIPTIONS,
   inspect: {
     run: "Inspect run state",
     viewer: "Start inspection viewer",
@@ -250,7 +244,8 @@ function buildCliHelpLines() {
     "Use `dev-loops <category> <subcommand> --help` for per-subcommand usage.",
     "",
     "`/dev-loops hide` remains an extension-only Pi command.",
-    "Run via `npx dev-loops` (or `npm install -g dev-loops` for the shell command); see the",
+    "Run via `npx dev-loops@<version>` pinned to your plugin/extension version (a global",
+    "`npm install -g dev-loops` can drift and is not the supported invocation path); see the",
     "README for Pi-extension and Claude Code plugin setup.",
   ];
 }
@@ -273,7 +268,7 @@ function orderedCliSetupSteps(checks) {
   return [
     "1. Use `/dev-loop` (Claude Code) or `/skill:dev-loop` (Pi) to start or continue a dev loop — the single public entry.",
     "2. Run `dev-loops status` whenever you want a concise readiness snapshot.",
-    "3. Run via `npx dev-loops` (or `npm install -g dev-loops` for the shell command); see the README for Pi-extension and Claude Code plugin setup.",
+    "3. Run via `npx dev-loops@<version>` pinned to your plugin/extension version (a global `npm install -g dev-loops` can drift and is not the supported invocation path); see the README for Pi-extension and Claude Code plugin setup.",
   ];
 }
 

package/extension/README.md

@@ -9,6 +9,8 @@ Installing the package exposes two thin wrappers over one shared deterministic c
 
 Installing the package with `pi install git:github.com/mfittko/dev-loops` exposes the packaged skills through `package.json` `pi.skills`, and the extension syncs packaged agent files (`agents/*.agent.md`) into `~/.agents/` on `session_start`.
 
+**Version pinning (no global-install skew).** The extension resolves both the CLI and `@dev-loops/core` from the installed, pinned package (module imports, not a global `dev-loops` binary), and updates itself via the pinned `pi update git:github.com/mfittko/dev-loops` seam above. It never depends on a separately-updated global install, so it stays in lockstep with the installed version by construction (#1036).
+
 ## Command surface
 
 - `/dev-loops`
@@ -144,7 +146,6 @@ autonomy:
 
 workflow:
   requireRetrospective: true
-  requireRetrospectiveGate: true
   requireDraftFirst: true
   devModeDefault: true
 ```
@@ -178,13 +179,12 @@ The optional `workflow` family carries repo-level workflow posture without hardc
 ```yaml
 workflow:
   requireRetrospective: false
-  requireRetrospectiveGate: false
   requireDraftFirst: false
   devModeDefault: false
 ```
 
 - `requireRetrospective` — when enabled by repo settings, the next qualifying GitHub-first async start/resume must honor the retrospective checkpoint gate
-- `requireRetrospectiveGate` — when enabled by repo settings, merge readiness after `pre_approval_gate` requires a completed retrospective checkpoint that explicitly approves merge. The retrospective must include: `state: "complete"`, `mergeApproved: true`, `followedWorkingAgreement` (boolean), `gateQuality` (string), `unexpectedFindings` (string), and `mergeRecommendation` (string). A `SKIPPED` retrospective does not satisfy the merge gate when this flag is enabled.
+- `requireRetrospectiveGate` — **removed (issue #1077)**. The retrospective is now advisory: it always runs and returns findings to the conductor via the envelope's `retrospectiveFindings` field and an advisory PR comment, never blocking merge or any transition. There is no longer a merge-gate config key for the retrospective.
 - `requireDraftFirst` — marks draft-first PR creation as required workflow policy for repos that opt in
 - `devModeDefault` — declares that local implementation should default to formal dev mode; this is config-only for now and establishes source-of-truth config plus docs for future runtime consumers
 
@@ -222,7 +222,7 @@ Current Phase 3+ contract:
 
 Root verification and test commands are intentionally explicit:
 - `npm run verify` is the canonical root verification path (`npm test` + `npm run test:dev-loop`)
-- `npm test` runs the current root test suite (`test:assets`, `test:extension`, `test:scripts`, and `test:core`)
+- `npm test` runs the current root test suite (`test:assets`, `test:extension`, `test:scripts`, `test:core`, and `test:docs`)
 - `npm run test:extension`
 - `npm run test:extension` currently expands to one `node --import tsx --test ...` invocation in `package.json`; prefer the script entrypoint over copying the file list into downstream docs or runbooks
 - `npm run test:scripts`

package/extension/checks.ts

@@ -1,4 +1,4 @@
-import { collectDevLoopChecks as collectSharedDevLoopChecks, DEV_LOOP_CHECK_IDS } from '../lib/dev-loops-core.mjs';
+import { DEV_LOOP_CHECK_IDS } from '../lib/dev-loops-core.mjs';
 import { createInspectRunViewerLifecycleManager } from '../scripts/loop/inspect-run-viewer/managed-instance.mjs';
 import type { ExtensionHarnessAdapter } from './harness-types.ts';
 
@@ -77,7 +77,3 @@ export function createExtensionCoreRuntime(
     },
   };
 }
-
-export async function collectDevLoopChecks(adapter: ExtensionHarnessAdapter): Promise<DevLoopCheck[]> {
-  return collectSharedDevLoopChecks(createExtensionCoreRuntime(adapter));
-}

package/extension/harness-types.ts

@@ -29,6 +29,7 @@ export type HarnessContext = {
   cwd: string;
   hasUI: boolean;
   ui: HarnessUi;
+  sendUserMessage?: (message: string, options?: Record<string, unknown>) => unknown;
 };
 
 export type HarnessLifecycleEvent = 'session_start' | 'tool_result' | 'user_bash' | 'agent_end';

package/extension/index.ts

@@ -8,6 +8,7 @@ import { createExtensionCoreRuntime } from './checks.ts';
 import { createPostMergeUpdateHook } from './post-merge-update.ts';
 import { createPiExtensionAdapter, type ExtensionAPI } from './pi-extension-adapter.ts';
 import {
+  buildEntrypointLines,
   buildHelpLines,
   buildInspectLines,
   buildInspectNotification,
@@ -25,6 +26,10 @@ const STATUS_KEY = 'dev-loops';
 const WIDGET_KEY = 'dev-loops.setup';
 const PACKAGED_AGENTS_ROOT = new URL('../agents/', import.meta.url);
 
+async function dispatchDevLoopIntent(ctx: { sendUserMessage?: (message: string) => unknown }, intent: string) {
+  await ctx.sendUserMessage?.(`/skill:dev-loop ${intent}`);
+}
+
 export function syncPackagedAgents({
   sourceRoot = fileURLToPath(PACKAGED_AGENTS_ROOT),
   targetRoot = path.join(os.homedir(), '.agents'),
@@ -72,7 +77,7 @@ export default function (pi: ExtensionAPI, runtimeOverrides: ExtensionRuntimeOve
   });
 
   adapter.registerCommand('dev-loops', {
-    description: 'Manage dev-loops readiness and inspect-run local UI lifecycle: /dev-loops [help|status|doctor|gates|hide|inspect ...]',
+    description: 'Run a dev-loop entrypoint or manage readiness: /dev-loops [start <issue>|auto <issue>|continue [issue|pr]|start-spike <question>|info <issue|pr>|status|doctor|gates|hide|inspect ...]',
     handler: async (args, ctx) => {
       const result = await executeDevLoopsCommand({
         input: args,
@@ -89,6 +94,16 @@ export default function (pi: ExtensionAPI, runtimeOverrides: ExtensionRuntimeOve
           ctx.ui.setWidget(WIDGET_KEY, buildHelpLines(), { placement: 'belowEditor' });
           ctx.ui.notify('dev-loops help', 'info');
           return;
+        case 'entrypoint':
+          ctx.ui.setWidget(WIDGET_KEY, buildEntrypointLines(result.action, result.intent), { placement: 'belowEditor' });
+          await dispatchDevLoopIntent(ctx, result.intent);
+          ctx.ui.notify(`dev-loops ${result.action}: ${result.intent}`, 'info');
+          return;
+        case 'start_spike':
+          ctx.ui.setWidget(WIDGET_KEY, buildEntrypointLines('start-spike', result.intent), { placement: 'belowEditor' });
+          await dispatchDevLoopIntent(ctx, result.intent);
+          ctx.ui.notify(`dev-loops start-spike: ${result.intent}`, 'info');
+          return;
         case 'checks':
           ctx.ui.setWidget(WIDGET_KEY, buildWidgetLines(result.action as Extract<DevLoopsAction, 'doctor' | 'status'>, result.checks), {
             placement: 'belowEditor',

package/extension/pi-extension-adapter.ts

@@ -26,6 +26,7 @@ import type {
 
 export function toHarnessContext(ctx: Partial<ExtensionContext> | undefined): HarnessContext {
   const ui = ctx?.ui;
+  const sender = (ctx as { sendUserMessage?: (message: string, options?: Record<string, unknown>) => unknown } | undefined)?.sendUserMessage;
   return {
     cwd: (ctx?.cwd as string) ?? process.cwd(),
     hasUI: Boolean(ctx?.hasUI),
@@ -34,6 +35,7 @@ export function toHarnessContext(ctx: Partial<ExtensionContext> | undefined): Ha
       setWidget: (key, lines, options) => ui?.setWidget?.(key, lines as never, options as never),
       setStatus: (key, text) => ui?.setStatus?.(key, text as never),
     },
+    sendUserMessage: sender ? (message, options) => sender.call(ctx, message, options) : undefined,
   };
 }
 

package/extension/presentation.ts

@@ -19,7 +19,7 @@ function checkMap(checks: DevLoopCheck[]): Map<DevLoopCheckId, DevLoopCheck> {
   return new Map(checks.map((check) => [check.id, check]));
 }
 
-export function orderedSetupSteps(checks: DevLoopCheck[]): string[] {
+function orderedSetupSteps(checks: DevLoopCheck[]): string[] {
   const byId = checkMap(checks);
   const uniqueSteps = [...new Set(DEV_LOOP_CHECK_IDS.filter((id) => byId.get(id)?.ok === false).map((id) => SETUP_GUIDANCE[id]))];
   const steps = uniqueSteps.map((step, index) => `${index + 1}. ${step}`);
@@ -35,21 +35,24 @@ export function orderedSetupSteps(checks: DevLoopCheck[]): string[] {
   ];
 }
 
+export function buildEntrypointLines(action: string, intent: string): string[] {
+  return [
+    `dev-loops ${action}`,
+    `Dispatch this public intent through the dev-loop skill:`,
+    `/skill:dev-loop ${intent}`,
+    'The dev-loop skill resolves authoritative state and routes deterministically — no strategy choice needed.',
+  ];
+}
+
 export function buildHelpLines(): string[] {
   return [
     'dev-loops help',
-    'Workflow entry:',
-    '- /skill:dev-loop — single public entrypoint; routing handles the rest',
-    'Commands:',
-    '- /dev-loops status',
-    '- /dev-loops doctor',
-    '- /dev-loops hide',
-    '- /dev-loops inspect open [--repo <owner/name>]',
-    '- /dev-loops inspect resume [--repo <owner/name>]',
-    '- /dev-loops inspect status [--repo <owner/name>]',
-    '- /dev-loops inspect stop [--repo <owner/name>]',
-    '- /dev-loops inspect restart [--repo <owner/name>]',
-    'Use `pi install git:github.com/mfittko/dev-loops` to install skills and agents; packaged agents sync into `~/.agents/` on session start.',
+    '/skill:dev-loop <intent> starts the public loop',
+    '/dev-loops start <issue> | /dev-loops auto <issue>',
+    '/dev-loops continue [issue|pr] | /dev-loops info <issue|pr>',
+    '/dev-loops start-spike <question>',
+    '/dev-loops inspect open|resume|status|stop|restart',
+    '/dev-loops status | /dev-loops doctor | /dev-loops hide',
   ];
 }
 

package/lib/dev-loops-core.mjs

@@ -9,6 +9,19 @@ const LOCAL_READINESS_IDS = ['subagent-command', 'git-repo'];
 const REMOTE_READINESS_IDS = ['gh-installed', 'gh-auth', 'subagent-command', 'git-repo'];
 const INSPECT_ACTIONS = new Set(['open', 'resume', 'status', 'stop', 'restart']);
 
+// Direct dev-loop entrypoints (#972): thin named wrappers over the public dev-loop contract.
+// Each maps `<verb> <issue|pr>` to the canonical public-intent shorthand the `dev-loop` skill
+// already accepts — no new routing/strategy logic lives here. `start`/`auto` target an issue,
+// `continue` (#988) targets an issue OR a PR (the resolver picks the canonical artifact) and
+// also accepts a bare form (no number) that continues the current in-progress board item;
+// `info` is the read-only state shortcut for an issue or PR.
+const ENTRYPOINT_VERBS = {
+  start: { target: 'issue', phrase: (n) => `start dev loop on issue ${n}` },
+  auto: { target: 'issue', phrase: (n) => `auto dev loop on issue ${n}` },
+  continue: { target: 'either', allowBare: true, phrase: (n) => (n ? `continue dev loop on ${n}` : 'continue the current dev loop') },
+  info: { target: 'either', phrase: (n) => `inspect dev loop state on ${n}` },
+};
+
 const UNICODE_SPACE_RE = /[\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000]/g;
 
 function normalizeInput(input) {
@@ -88,6 +101,100 @@ function parseInspectCommand(tokens, { surface }) {
   };
 }
 
+// Normalize a single entrypoint target token to a bare issue/PR number.
+// Accepts `123`, `#123`, or a GitHub issue/PR URL (.../issues/123 or .../pull/123).
+// Returns the numeric string, or null when it is not a recognized target.
+function normalizeTargetNumber(raw) {
+  const token = String(raw).trim();
+  if (/^#?\d+$/.test(token)) {
+    return token.replace(/^#/, '');
+  }
+  const urlMatch = token.match(/^https?:\/\/[^\s]*\/(?:issues|pull)\/(\d+)(?:[/?#].*)?$/);
+  if (urlMatch) {
+    return urlMatch[1];
+  }
+  return null;
+}
+
+// `start-spike` is a SIBLING of the numeric verbs (start/auto/continue/info): it
+// takes FREE TEXT (a question) or `--file <path>`, NOT a numeric target, so it is
+// parsed on its own path to keep the numeric-validation invariant of the other
+// verbs intact (#988 P2). It is a thin wrapper over the shipped `--spike` intake:
+// the inline-question form scaffolds a startable findings artifact, then both
+// forms hand the resolved spike path to `loop startup --spike <path>`. No new
+// spike behavior lives here — see skills/docs/spike-mode-contract.md.
+function parseStartSpikeCommand(rest, tokens) {
+  const positional = rest.filter((t) => t !== undefined);
+  // `--file <path>`: start from a pre-authored spike artifact (no scaffolding).
+  if (positional[0] === '--file') {
+    const file = positional[1];
+    // Reject any leading `-`: the path is forwarded to `resolve-dev-loop-startup
+    // --spike <path>`, so a value like `-x` could be read as an option (option
+    // injection). Fail closed. The free-text question path below is unaffected.
+    if (typeof file !== 'string' || file.length === 0 || file.startsWith('-') || positional.length !== 2) {
+      return invalidCommand('`start-spike --file` requires exactly one `<path>`.', 'start-spike', tokens);
+    }
+    return {
+      kind: 'start_spike',
+      mode: 'file',
+      file,
+      question: null,
+      intent: `start a dev-loop spike from ${file}`,
+      tokens,
+    };
+  }
+  // Inline free-text question. Joined verbatim so multi-word questions survive.
+  const question = positional.join(' ').trim();
+  if (question.length === 0) {
+    return invalidCommand('`start-spike` requires a question (or `--file <path>`).', 'start-spike', tokens);
+  }
+  return {
+    kind: 'start_spike',
+    mode: 'question',
+    file: null,
+    question,
+    intent: `start a dev-loop spike on the question: ${question}`,
+    tokens,
+  };
+}
+
+function parseEntrypointCommand(action, args, tokens) {
+  const spec = ENTRYPOINT_VERBS[action];
+  const positional = args.filter((a) => a !== undefined);
+  const targetHint = spec.target === 'pr' ? '<pr>' : spec.target === 'either' ? '<issue|pr>' : '<issue>';
+  const targetNoun = spec.target === 'pr' ? 'PR' : spec.target === 'either' ? 'issue/PR' : 'issue';
+
+  // Bare form (no target): only verbs that opt in (e.g. `continue` resumes the
+  // current in-progress board item). The command/skill does the board resolve.
+  if (positional.length === 0 && spec.allowBare) {
+    return {
+      kind: 'entrypoint',
+      action,
+      target: spec.target,
+      number: null,
+      intent: spec.phrase(null),
+      tokens,
+    };
+  }
+
+  if (positional.length !== 1) {
+    const arity = spec.allowBare ? `at most one ${targetHint}` : `exactly one ${targetHint}`;
+    return invalidCommand(`\`${action}\` requires ${arity} argument.`, action, tokens);
+  }
+  const number = normalizeTargetNumber(positional[0]);
+  if (number === null) {
+    return invalidCommand(`\`${action}\` expects a numeric ${targetNoun}, got: ${positional[0]}.`, action, tokens);
+  }
+  return {
+    kind: 'entrypoint',
+    action,
+    target: spec.target,
+    number,
+    intent: spec.phrase(number),
+    tokens,
+  };
+}
+
 export function parseDevLoopsCommand(input, { surface = 'extension' } = {}) {
   const tokens = normalizeInput(input);
   const [rawAction, rawScope, ...rest] = tokens;
@@ -98,6 +205,15 @@ export function parseDevLoopsCommand(input, { surface = 'extension' } = {}) {
     return parseInspectCommand(tokens, { surface });
   }
 
+  // `start-spike` is free-text/path, not a numeric verb — parsed on its own path.
+  if (action === 'start-spike') {
+    return parseStartSpikeCommand([rawScope, ...rest], tokens);
+  }
+
+  if (action && Object.prototype.hasOwnProperty.call(ENTRYPOINT_VERBS, action)) {
+    return parseEntrypointCommand(action, [rawScope, ...rest], tokens);
+  }
+
   switch (action) {
     case undefined:
     case '':
@@ -255,6 +371,31 @@ export async function executeDevLoopsCommand({ input, surface = 'extension', run
     }
   }
 
+  if (parsed.kind === 'start_spike') {
+    // Thin wrapper: surface the spike intent so the operator dispatches it through
+    // the dev-loop skill, which scaffolds (inline question) or uses the given file,
+    // then runs `loop startup --spike <path>`. No spike behavior is decided here.
+    return {
+      kind: 'start_spike',
+      mode: parsed.mode,
+      file: parsed.file,
+      question: parsed.question,
+      intent: parsed.intent,
+    };
+  }
+
+  if (parsed.kind === 'entrypoint') {
+    // Thin wrapper: surface the canonical public intent so the user dispatches it through the
+    // `dev-loop` skill (the single public router). No routing/strategy decision is made here.
+    return {
+      kind: 'entrypoint',
+      action: parsed.action,
+      target: parsed.target,
+      number: parsed.number,
+      intent: parsed.intent,
+    };
+  }
+
   if (parsed.kind !== 'action') {
     return parsed;
   }

package/package.json

@@ -24,13 +24,15 @@
     "verify": "npm test && npm run test:dev-loop",
     "test": "npm run test:assets && npm run test:extension && npm run test:scripts && npm run test:core && npm run test:docs",
     "test:assets": "node --test --test-reporter ./test/failure-summary-reporter.mjs test/dev-loop-init-phase-smoke.test.mjs test/contracts/*.test.mjs test/workflow-handoff-contract.test.mjs",
-    "test:extension": "node --import tsx --test --test-reporter ./test/failure-summary-reporter.mjs test/extension-checks.test.mjs test/extension-post-merge-update.test.mjs test/extension-command-contract.test.mjs test/extension-package-contract.test.mjs test/extension-pi-adapter.test.mjs test/extension-claude-adapter.test.mjs test/dev-loops-core.test.mjs test/dev-loops-cli.test.mjs",
-    "test:scripts": "node --test --test-reporter ./test/failure-summary-reporter.mjs test/github/*.test.mjs test/loop/*.test.mjs test/docs/*.test.mjs test/projects/*.test.mjs test/pages/*.test.mjs",
+    "test:extension": "node --import tsx --test --test-reporter ./test/failure-summary-reporter.mjs test/extension-checks.test.mjs test/extension-post-merge-update.test.mjs test/extension-command-contract.test.mjs test/extension-package-contract.test.mjs test/extension-pi-adapter.test.mjs test/dev-loops-core.test.mjs test/dev-loops-cli.test.mjs",
+    "test:scripts": "GIT_CONFIG_COUNT=2 GIT_CONFIG_KEY_0=core.fsync GIT_CONFIG_VALUE_0=none GIT_CONFIG_KEY_1=core.fsyncObjectFiles GIT_CONFIG_VALUE_1=false node --test --test-reporter ./test/failure-summary-reporter.mjs test/github/*.test.mjs test/loop/*.test.mjs test/docs/*.test.mjs test/projects/*.test.mjs test/pages/*.test.mjs",
     "test:core": "node --test --test-reporter ./test/failure-summary-reporter.mjs packages/core/test/*.test.mjs",
     "test:dev-loop": "node --test --test-reporter ./test/failure-summary-reporter.mjs skills/dev-loop/scripts/dev-mode-context.test.mjs skills/dev-loop/scripts/render-template.test.mjs skills/dev-loop/scripts/post-gate-verdict-fallback.test.mjs",
-    "test:playwright:viewer": "playwright test -c playwright.inspect-run-viewer.config.mjs",
-    "test:playwright:deep-dive": "playwright test -c playwright.dev-loops-deep-dive.config.mjs",
-    "test:playwright:intro-deck": "playwright test -c playwright.intro-deck.config.mjs",
+    "test:playwright:viewer": "PW_UI_SLICE=inspect-run-viewer playwright test --project=inspect-run-viewer",
+    "test:playwright:deep-dive": "PW_UI_SLICE=deep-dive-deck playwright test --project=deep-dive-deck",
+    "test:playwright:intro-deck": "PW_UI_SLICE=intro-deck playwright test --project=intro-deck",
+    "test:playwright:intro-article": "PW_UI_SLICE=intro-article playwright test --project=intro-article",
+    "test:playwright:deep-dive-article": "PW_UI_SLICE=deep-dive-article playwright test --project=deep-dive-article",
     "smoke:headless": "node scripts/claude/headless-info-smoke.mjs",
     "test:docs": "node scripts/docs/validate-links.mjs && node scripts/docs/validate-no-duplicate-rules.mjs",
     "repo-wiki": "node scripts/repo-wiki.mjs",
@@ -69,8 +71,7 @@
     ]
   },
   "dependencies": {
-    "mermaid": "11.15.0",
-    "@dev-loops/core": "^0.5.0"
+    "@dev-loops/core": "^0.7.1"
   },
   "repository": {
     "type": "git",
@@ -80,7 +81,7 @@
     "url": "https://github.com/mfittko/dev-loops/issues"
   },
   "homepage": "https://github.com/mfittko/dev-loops#readme",
-  "version": "0.5.0",
+  "version": "0.7.1",
   "files": [
     "cli/",
     "lib/",
@@ -91,6 +92,7 @@
     ".claude-plugin/",
     ".claude/.claude-plugin/",
     ".claude/agents/",
+    ".claude/commands/",
     ".claude/skills/",
     ".claude/hooks/",
     "README.md",