dev-loops 0.1.3 → 0.2.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "dev-loops",
+  "owner": {
+    "name": "Manuel Fittko",
+    "email": "manuel.fittko@sofatutor.com"
+  },
+  "description": "Turn GitHub issues into merged PRs: agent-harness-agnostic dev-loop agents, skills, and hooks for Claude Code.",
+  "plugins": [
+    {
+      "name": "dev-loops",
+      "source": "./.claude",
+      "description": "Agent-harness-agnostic dev-loop: agents, skills, and hooks for GitHub/Copilot-driven development loops.",
+      "homepage": "https://github.com/mfittko/dev-loops#readme",
+      "repository": "https://github.com/mfittko/dev-loops.git",
+      "license": "MIT",
+      "keywords": ["dev-loop", "workflow", "github", "copilot", "claude-code", "plugin"]
+    }
+  ]
+}

package/CHANGELOG.md

@@ -2,6 +2,76 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.2.1
+
+### Added
+
+- **Claude Code marketplace catalog** (#828): ship `.claude-plugin/marketplace.json` at the repo
+  root so the repo can be added as a plugin marketplace (`/plugin marketplace add mfittko/dev-loops`,
+  or the *Manage Plugins → Marketplaces → Add* UI) and the plugin installed with
+  `/plugin install dev-loops@dev-loops`. The catalog's single plugin entry sources the existing
+  in-repo plugin at `./.claude`; the plugin version stays authoritative in `plugin.json`. A
+  contract test locks the catalog shape, and `.claude-plugin/` is added to the npm `files`
+  allowlist. Verified end-to-end with `claude plugin validate` + `marketplace add`/`install`
+  (4 skills, 7 agents, 2 hooks).
+
+### Changed
+
+- `plugin.json` now declares an `author` (clears the marketplace-validation warning).
+- README "Claude Code plugin" section drops the `(preview)` framing and documents marketplace
+  install; the two CLI help lines that said plugin packaging was "in progress" are updated.
+
+## 0.2.0
+
+### Added — Claude Code harness (agent-harness-agnostic dev-loop)
+
+dev-loops is now dual-harness: it runs under both Pi and Claude Code. Pi behavior is unchanged.
+
+- **Harness adapter seam** (#770): a neutral `ExtensionHarnessAdapter` (exec + lifecycle +
+  command registration + ui) with Pi and Claude adapters; `@dev-loops/core/harness`.
+- **Neutral run-id contract** (#771): `DEVLOOPS_RUN_ID` (with `PI_SUBAGENT_RUN_ID` as a
+  backward-compatible alias) via `@dev-loops/core/loop/run-context`; all runner-coordination /
+  async-start readers route through it.
+- **Generated `.claude` assets** (#772, #816, #817): a deterministic generator emits
+  `.claude/agents` + `.claude/skills` from the canonical Pi sources (`@dev-loops/core/claude/
+  asset-generation`), with the Pi→Claude tool-name mapping, bundled shared contract docs +
+  templates, and Pi-runtime-only prose stripped via `<!-- pi-only -->` markers.
+- **Claude hooks + read-only enforcement** (#773): PreToolUse Bash draft-gate guard + Write/Edit
+  main-agent read-only guard (`@dev-loops/core/claude/hook-decisions`), opt-in via
+  `DEVLOOPS_MAIN_AGENT_READONLY`.
+- **CLI Pi-neutrality** (#774): `npx dev-loops --help`/`status` run with no `@earendil-works/pi-*`
+  present; Pi-only install strings no longer shown unconditionally.
+- **Headless entry** (#775): a `claude -p` headless dev-loop entry (`@dev-loops/core/claude/
+  headless-entry`) that mints + propagates the run id, plus an offline read-only CI/Docker smoke
+  (`npm run smoke:headless`); the Pi Docker smoke is preserved (dual-harness).
+- **Claude Code plugin** (#818, #824): `.claude/.claude-plugin/plugin.json` (plugin root
+  `.claude/`) bundling the dev-loop agents, skills, and hooks —
+  `claude --plugin-dir .claude` loads 4 skills, 7 agents, 2 hooks.
+
+### Changed
+
+- `@dev-loops/core` bumped to `^0.2.0` (new `claude/*`, `loop/run-context`, and
+  `loop/bash-command-classify` exports).
+
+## 0.1.3
+
+### Fixed
+
+- Removed a stale `defaults.yaml` from the `files` allowlist and regenerated the lockfile (#806).
+
+## 0.1.2
+
+### Changed
+
+- Ship the extension-packaged dev-loop defaults only; removed the duplicated
+  `.pi/dev-loop/defaults.yaml` (#805).
+
+## 0.1.1
+
+### Changed
+
+- Renamed the Pi peer dependencies to the `@earendil-works/pi-*` scope (#799).
+
 ## 0.1.0
 
 ### Added

package/README.md

@@ -45,6 +45,34 @@ Or run directly without installing:
 npx dev-loops --help
 ```
 
+### Claude Code plugin
+
+The repo ships a Claude Code plugin rooted at `.claude/` (manifest at
+`.claude/.claude-plugin/plugin.json`) exposing the dev-loop **agents, skills, and hooks**.
+
+Install it from the bundled marketplace catalog (`.claude-plugin/marketplace.json`) by running
+these slash commands inside Claude Code:
+
+```text
+/plugin marketplace add mfittko/dev-loops    # register the marketplace
+/plugin install dev-loops@dev-loops          # install the plugin
+```
+
+Or load it directly for a single session without installing:
+
+```bash
+claude --plugin-dir .claude                              # load it for a session
+claude --plugin-dir .claude plugin details dev-loops     # inspect the discovered components
+```
+
+When installed from npm, point at the bundled copy: `claude --plugin-dir node_modules/dev-loops/.claude`.
+
+The plugin is self-contained: it bundles the shared contract docs and templates the skills
+reference, and strips Pi-runtime-only prose from the generated assets. The hooks provide the
+`gh pr ready` draft-gate guard and the main-agent read-only boundary (the read-only enforcement
+is opt-in via `DEVLOOPS_MAIN_AGENT_READONLY=1`). Skill references to a project's own `PLAN.md` /
+`AGENTS.md` resolve against the consumer repo, by design.
+
 ### Pi extension
 
 To use `/dev-loops` inside Pi:

package/agents/dev-loop.agent.md

@@ -59,7 +59,9 @@ 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.
+<!-- /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.
 
@@ -68,12 +70,14 @@ The pi-subagents skill is parent-only, so delegated subagents do not receive orc
 - No child subagent spawning beyond assigned fanout work.
 - Bounded tasks with concrete scope, exit conditions, and validation expectations.
 
+<!-- pi-only -->
 **Supervisor communication (known pi runtime bug #671):** The pi runtime `contact_supervisor` tool has a broken response path — supervisor responses do not flow back to resolve the pending subagent tool call. Subagents calling `contact_supervisor` become blocked until the idle timeout fires (~60s), then pause without the decision.
 
 - **Prefer `intercom` when available.** If the `pi-intercom` extension is active, use `intercom({ action: "ask", ... })` instead of `contact_supervisor`. The `intercom` tool uses message-based delivery (no blocking tool-call state) — see the pi documentation for `intercom({ action: "ask", ... })` parameters and reply conventions.
 - **When `intercom` is unavailable,** do not call `contact_supervisor`. Instead, brief the supervisor to include the decision in the resume message when re-dispatching. The subagent states what it needs in the task description; the supervisor provides the answer on resume. This avoids the broken response path entirely.
 - **If `contact_supervisor` was already called** (legacy code or unavoidable): expect a ~60s idle timeout followed by a pause. On resume, the supervisor must inject the decision in the resume message — do not rely on `intercom` on resume when it was unavailable at call time.
 - **Timeout detection (supervisor-side):** if a `contact_supervisor` call has been pending for >30s, the supervisor should treat it as a probable timeout and prepare to inject the decision in the resume message on re-dispatch. The subagent cannot execute this detection while blocked inside `contact_supervisor`; the supervisor must observe the pending duration externally.
+<!-- /pi-only -->
 
 ## Output
 

package/cli/index.mjs

@@ -195,7 +195,7 @@ function buildCliHelpLines() {
     "dev-loops help",
     "",
     "Workflow entry:",
-    "- /skill:dev-loop (in Pi) or `subagent dev-loop` — single public entrypoint; routing handles the rest",
+    "- `/dev-loop` (Claude Code) or `/skill:dev-loop` (Pi) — single public entrypoint; routing handles the rest",
     "",
     "Commands:",
     "- dev-loops help                   Show this help",
@@ -209,8 +209,8 @@ function buildCliHelpLines() {
     "Use `dev-loops <category> <subcommand> --help` for per-subcommand usage.",
     "",
     "`/dev-loops hide` remains an extension-only Pi command.",
-    "Use `pi install git:github.com/mfittko/dev-loops` to install skills and agents, or",
-    "`pi update git:github.com/mfittko/dev-loops` to refresh the package.",
+    "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.",
   ];
 }
 
@@ -230,9 +230,9 @@ function orderedCliSetupSteps(checks) {
   const steps = [...new Set(DEV_LOOP_CHECK_IDS.filter((id) => byId.get(id)?.ok === false).map((id) => CLI_SETUP_GUIDANCE[id]))];
   if (steps.length > 0) return steps.map((step, i) => `${i + 1}. ${step}`);
   return [
-    "1. Use `/skill:dev-loop` (in Pi) or `subagent dev-loop` to start or continue a dev loop — the single public entry.",
+    "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. Use `pi install git:github.com/mfittko/dev-loops` to install the package, or `pi update git:github.com/mfittko/dev-loops` to refresh it.",
+    "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.",
   ];
 }
 

package/extension/checks.ts

@@ -1,7 +1,6 @@
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-
 import { collectDevLoopChecks as collectSharedDevLoopChecks, 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';
 
 export type DevLoopCheckId = (typeof DEV_LOOP_CHECK_IDS)[number];
 
@@ -12,47 +11,37 @@ export type DevLoopCheck = {
   detail: string;
 };
 
-async function commandExists(pi: ExtensionAPI, command: string): Promise<boolean> {
+async function commandExists(adapter: ExtensionHarnessAdapter, command: string): Promise<boolean> {
   try {
-    const result = await pi.exec('bash', ['-lc', `command -v ${command} >/dev/null 2>&1`], {
-      timeout: 5_000,
-    });
+    const result = await adapter.exec(`command -v ${command} >/dev/null 2>&1`, { timeout: 5_000 });
     return result.code === 0;
   } catch {
     return false;
   }
 }
 
-async function ghAuthOk(pi: ExtensionAPI): Promise<boolean> {
+async function ghAuthOk(adapter: ExtensionHarnessAdapter): Promise<boolean> {
   try {
-    const result = await pi.exec('bash', ['-lc', 'gh auth status >/dev/null 2>&1'], {
-      timeout: 10_000,
-    });
+    const result = await adapter.exec('gh auth status >/dev/null 2>&1', { timeout: 10_000 });
     return result.code === 0;
   } catch {
     return false;
   }
 }
 
-async function insideGitRepo(pi: ExtensionAPI): Promise<boolean> {
+async function insideGitRepo(adapter: ExtensionHarnessAdapter): Promise<boolean> {
   try {
-    const result = await pi.exec(
-      'bash',
-      ['-lc', 'git rev-parse --is-inside-work-tree >/dev/null 2>&1'],
-      { timeout: 5_000 },
-    );
+    const result = await adapter.exec('git rev-parse --is-inside-work-tree >/dev/null 2>&1', { timeout: 5_000 });
     return result.code === 0;
   } catch {
     return false;
   }
 }
 
-async function getRepoRoot(pi: ExtensionAPI): Promise<string> {
-  const result = await pi.exec('bash', ['-lc', 'git rev-parse --show-toplevel'], {
-    timeout: 10_000,
-  });
+async function getRepoRoot(adapter: ExtensionHarnessAdapter): Promise<string> {
+  const result = await adapter.exec('git rev-parse --show-toplevel', { timeout: 10_000 });
   if (result.code !== 0) {
-    throw new Error('Open Pi inside a git repository before using `/dev-loops inspect`.');
+    throw new Error('Open this session inside a git repository before using `/dev-loops inspect`.');
   }
   const repoRoot = `${result.stdout ?? ''}`.trim();
   if (!repoRoot) {
@@ -62,7 +51,7 @@ async function getRepoRoot(pi: ExtensionAPI): Promise<string> {
 }
 
 export function createExtensionCoreRuntime(
-  pi: ExtensionAPI,
+  adapter: ExtensionHarnessAdapter,
   {
     uiLifecycle = createInspectRunViewerLifecycleManager(),
     getRepoRoot: getRepoRootOverride,
@@ -73,13 +62,13 @@ export function createExtensionCoreRuntime(
 ) {
   return {
     surface: 'extension' as const,
-    commandExists: (command: string) => commandExists(pi, command),
-    ghAuthOk: () => ghAuthOk(pi),
-    insideGitRepo: () => insideGitRepo(pi),
-    getRepoRoot: () => (getRepoRootOverride ? getRepoRootOverride() : getRepoRoot(pi)),
+    commandExists: (command: string) => commandExists(adapter, command),
+    ghAuthOk: () => ghAuthOk(adapter),
+    insideGitRepo: () => insideGitRepo(adapter),
+    getRepoRoot: () => (getRepoRootOverride ? getRepoRootOverride() : getRepoRoot(adapter)),
     uiLifecycle,
     async getSubagentAvailability() {
-      const ok = await commandExists(pi, 'subagent');
+      const ok = await commandExists(adapter, 'subagent');
       return {
         ok,
         availableDetail: '`subagent` command is available.',
@@ -89,6 +78,6 @@ export function createExtensionCoreRuntime(
   };
 }
 
-export async function collectDevLoopChecks(pi: ExtensionAPI): Promise<DevLoopCheck[]> {
-  return collectSharedDevLoopChecks(createExtensionCoreRuntime(pi));
+export async function collectDevLoopChecks(adapter: ExtensionHarnessAdapter): Promise<DevLoopCheck[]> {
+  return collectSharedDevLoopChecks(createExtensionCoreRuntime(adapter));
 }

package/extension/harness-types.ts

@@ -0,0 +1,47 @@
+/**
+ * Neutral, harness-agnostic types for the extension surface.
+ *
+ * These mirror the JSDoc typedefs in
+ * `packages/core/src/harness/extension-adapter.mjs` so the `.ts` extension modules
+ * can share a single import-free type vocabulary. No `@earendil-works/pi-*` import
+ * lives here — that boundary is owned solely by `./pi-extension-adapter.ts`.
+ */
+
+export type HarnessExecResult = {
+  code?: number;
+  stdout?: string;
+  stderr?: string;
+  killed?: boolean;
+};
+
+export type HarnessExecOptions = {
+  cwd?: string;
+  timeout?: number;
+};
+
+export type HarnessUi = {
+  notify(message: string, level?: 'info' | 'warning' | 'error'): void;
+  setWidget(key: string, lines: string[] | undefined, options?: Record<string, unknown>): void;
+  setStatus(key: string, text: string | undefined): void;
+};
+
+export type HarnessContext = {
+  cwd: string;
+  hasUI: boolean;
+  ui: HarnessUi;
+};
+
+export type HarnessLifecycleEvent = 'session_start' | 'tool_result' | 'user_bash' | 'agent_end';
+
+export type HarnessCommandConfig = {
+  description: string;
+  handler: (args: string | string[], ctx: HarnessContext) => unknown;
+};
+
+export type HarnessLifecycleHandler = (event: unknown, ctx: HarnessContext) => unknown;
+
+export type ExtensionHarnessAdapter = {
+  exec(command: string, options?: HarnessExecOptions): Promise<HarnessExecResult>;
+  on(event: HarnessLifecycleEvent, handler: HarnessLifecycleHandler): void;
+  registerCommand(name: string, config: HarnessCommandConfig): void;
+};

package/extension/index.ts

@@ -2,11 +2,11 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 
 import { executeDevLoopsCommand } from '../lib/dev-loops-core.mjs';
 import { createExtensionCoreRuntime } from './checks.ts';
 import { createPostMergeUpdateHook } from './post-merge-update.ts';
+import { createPiExtensionAdapter, type ExtensionAPI } from './pi-extension-adapter.ts';
 import {
   buildHelpLines,
   buildInspectLines,
@@ -45,9 +45,11 @@ export function syncPackagedAgents({
 }
 
 export default function (pi: ExtensionAPI, runtimeOverrides: ExtensionRuntimeOverrides = {}) {
-  const postMergeUpdateHook = runtimeOverrides.postMergeUpdateHook ?? createPostMergeUpdateHook(pi);
+  // Wrap the Pi harness at the entry boundary; everything below talks to the neutral seam.
+  const adapter = createPiExtensionAdapter(pi);
+  const postMergeUpdateHook = runtimeOverrides.postMergeUpdateHook ?? createPostMergeUpdateHook({ exec: adapter.exec });
 
-  pi.on('session_start', async (_event, ctx) => {
+  adapter.on('session_start', async (_event, ctx) => {
     postMergeUpdateHook.onSessionStart();
     try {
       syncPackagedAgents();
@@ -57,25 +59,25 @@ export default function (pi: ExtensionAPI, runtimeOverrides: ExtensionRuntimeOve
     ctx.ui.setStatus(STATUS_KEY, undefined);
   });
 
-  pi.on('tool_result', async (event, ctx) => {
+  adapter.on('tool_result', async (event, ctx) => {
     await postMergeUpdateHook.onToolResult(event, ctx);
   });
 
-  pi.on('user_bash', async (event, ctx) => {
+  adapter.on('user_bash', async (event, ctx) => {
     return postMergeUpdateHook.onUserBash(event, ctx);
   });
 
-  pi.on('agent_end', async (event, ctx) => {
+  adapter.on('agent_end', async (event, ctx) => {
     await postMergeUpdateHook.onAgentEnd(event, ctx);
   });
 
-  pi.registerCommand('dev-loops', {
+  adapter.registerCommand('dev-loops', {
     description: 'Manage dev-loops readiness and inspect-run local UI lifecycle: /dev-loops [help|status|doctor|gates|hide|inspect ...]',
     handler: async (args, ctx) => {
       const result = await executeDevLoopsCommand({
         input: args,
         surface: 'extension',
-        runtime: createExtensionCoreRuntime(pi, runtimeOverrides),
+        runtime: createExtensionCoreRuntime(adapter, runtimeOverrides),
       });
 
       switch (result.kind) {

package/extension/pi-extension-adapter.ts

@@ -0,0 +1,64 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+
+import { createExtensionHarnessAdapter } from '@dev-loops/core/harness';
+
+// Re-exported so the rest of the extension can name the Pi entry type without importing
+// `@earendil-works/pi-*` directly — this module owns that import boundary.
+export type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+import type {
+  ExtensionHarnessAdapter,
+  HarnessContext,
+  HarnessCommandConfig,
+  HarnessExecOptions,
+  HarnessLifecycleEvent,
+  HarnessLifecycleHandler,
+} from './harness-types.ts';
+
+/**
+ * The single module allowed to import `@earendil-works/pi-*`.
+ *
+ * Wraps a Pi `ExtensionAPI` into the neutral `ExtensionHarnessAdapter` so the rest of
+ * the extension talks only to the neutral seam. Pi's per-invocation `ExtensionContext`
+ * is converted to a neutral `HarnessContext` at call time, so UI/cwd flow through
+ * unchanged — preserving today's behavior exactly.
+ */
+
+export function toHarnessContext(ctx: Partial<ExtensionContext> | undefined): HarnessContext {
+  const ui = ctx?.ui;
+  return {
+    cwd: (ctx?.cwd as string) ?? process.cwd(),
+    hasUI: Boolean(ctx?.hasUI),
+    ui: {
+      notify: (message, level = 'info') => ui?.notify?.(message, level),
+      setWidget: (key, lines, options) => ui?.setWidget?.(key, lines as never, options as never),
+      setStatus: (key, text) => ui?.setStatus?.(key, text as never),
+    },
+  };
+}
+
+export function createPiExtensionAdapter(pi: ExtensionAPI): ExtensionHarnessAdapter {
+  // Route through the shared factory so the Pi adapter gets the same validation + freeze
+  // guarantee as the Claude adapter (symmetric construction across harnesses).
+  return createExtensionHarnessAdapter({
+    async exec(command: string, options: HarnessExecOptions = {}) {
+      return pi.exec('bash', ['-lc', command], {
+        cwd: options.cwd,
+        timeout: options.timeout,
+      });
+    },
+
+    on(event: HarnessLifecycleEvent, handler: HarnessLifecycleHandler) {
+      pi.on(event as never, (async (piEvent: unknown, piCtx: ExtensionContext) =>
+        handler(piEvent, toHarnessContext(piCtx))) as never);
+    },
+
+    registerCommand(name: string, config: HarnessCommandConfig) {
+      pi.registerCommand(name, {
+        description: config.description,
+        handler: (async (args: string | string[], piCtx: ExtensionContext) =>
+          config.handler(args, toHarnessContext(piCtx))) as never,
+      });
+    },
+  }) as ExtensionHarnessAdapter;
+}