@syntesseraai/opencode-feature-factory 0.1.6 → 0.1.7

package/assets/agents/ff-validate.md

@@ -34,7 +34,6 @@ Launch these agents **in parallel** using the Task tool:
 
 | Agent                 | Purpose                 | Focus                                  |
 | --------------------- | ----------------------- | -------------------------------------- |
-| `ff-ci`               | CI checks               | Tests, build, lint, type-check         |
 | `ff-review`           | Code review             | Quality, correctness, maintainability  |
 | `ff-security`         | Security audit          | Vulnerabilities, auth, data protection |
 | `ff-acceptance`       | Requirements validation | Acceptance criteria, completeness      |
@@ -51,7 +50,6 @@ Launch these agents **in parallel** using the Task tool:
 
    ```
    Launch all agents simultaneously **in parallel**:
-   - Task(ff-ci): "Run CI checks on the changes"
    - Task(ff-review): "Review the code changes for quality"
    - Task(ff-security): "Audit the changes for security issues"
    - Task(ff-acceptance): "Validate against acceptance criteria: <criteria>"
@@ -88,11 +86,6 @@ Output your validation results as structured JSON:
     "rationale": "Security vulnerability and failing tests must be fixed"
   },
   "agents": {
-    "ci": {
-      "status": "failed",
-      "summary": "3 tests failing, build passed",
-      "blocking": true
-    },
     "review": {
       "status": "passed",
       "summary": "Code quality acceptable with minor suggestions",
@@ -124,13 +117,6 @@ Output your validation results as structured JSON:
         "line": 45,
         "description": "User input directly concatenated in SQL query",
         "fix": "Use parameterized queries"
-      },
-      {
-        "source": "ff-ci",
-        "severity": "high",
-        "title": "Test failures",
-        "description": "3 unit tests failing in UserService",
-        "fix": "Fix the failing assertions"
       }
     ],
     "nonBlocking": [
@@ -164,14 +150,12 @@ Output your validation results as structured JSON:
 
 ### Automatic Approval (approved: true)
 
-- All CI checks pass (tests, build, lint, types)
 - No critical or high severity security issues
 - All acceptance criteria met
 - No blocking issues from any agent
 
 ### Request Changes (approved: false)
 
-- Any CI check fails
 - Any security vulnerability found
 - Acceptance criteria not met
 - Critical architectural concerns

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@syntesseraai/opencode-feature-factory",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "OpenCode plugin for Feature Factory agents - provides planning, implementation, review, testing, and validation agents",
   "type": "module",
   "license": "MIT",
@@ -31,4 +31,4 @@
     "@types/node": "^22.0.0",
     "typescript": "^5.0.0"
   }
-}
+}

package/src/discovery.ts

@@ -0,0 +1,244 @@
+import type { CommandStep, PackageManager, QualityGateConfig } from './types';
+import {
+  DEFAULT_QUALITY_GATE,
+  fileExists,
+  hasConfiguredCommands,
+  readJsonFile,
+} from './quality-gate-config';
+
+// Shell type - uses `any` to be compatible with OpenCode's BunShell
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type BunShell = any;
+
+// ============================================================================
+// Package Manager Detection
+// ============================================================================
+
+/**
+ * Detect the package manager based on lockfile presence.
+ * Priority: pnpm > bun > yarn > npm
+ */
+async function detectPackageManager(
+  $: BunShell,
+  directory: string,
+  override?: string
+): Promise<PackageManager> {
+  if (override && override !== 'auto') {
+    return override as PackageManager;
+  }
+
+  // Priority order: pnpm > bun > yarn > npm
+  if (await fileExists($, `${directory}/pnpm-lock.yaml`)) return 'pnpm';
+  if (await fileExists($, `${directory}/bun.lockb`)) return 'bun';
+  if (await fileExists($, `${directory}/bun.lock`)) return 'bun';
+  if (await fileExists($, `${directory}/yarn.lock`)) return 'yarn';
+  if (await fileExists($, `${directory}/package-lock.json`)) return 'npm';
+
+  return 'npm'; // fallback
+}
+
+/**
+ * Build the run command for a given package manager and script name
+ */
+function buildRunCommand(pm: PackageManager, script: string): string {
+  switch (pm) {
+    case 'pnpm':
+      return `pnpm -s run ${script}`;
+    case 'bun':
+      return `bun run ${script}`;
+    case 'yarn':
+      return `yarn -s ${script}`;
+    case 'npm':
+      return `npm run -s ${script}`;
+  }
+}
+
+// ============================================================================
+// Node.js Discovery
+// ============================================================================
+
+/**
+ * Discover Node.js lint/build/test commands from package.json scripts
+ */
+async function discoverNodeCommands(
+  $: BunShell,
+  directory: string,
+  pm: PackageManager
+): Promise<CommandStep[]> {
+  const pkgJson = await readJsonFile($, `${directory}/package.json`);
+  if (!pkgJson?.scripts) return [];
+
+  const scripts = pkgJson.scripts as Record<string, string>;
+  const steps: CommandStep[] = [];
+
+  // Lint: prefer lint:ci, then lint
+  const lintScript = scripts['lint:ci'] ? 'lint:ci' : scripts['lint'] ? 'lint' : null;
+  if (lintScript) {
+    steps.push({ step: 'lint', cmd: buildRunCommand(pm, lintScript) });
+  }
+
+  // Build: prefer build:ci, then build
+  const buildScript = scripts['build:ci'] ? 'build:ci' : scripts['build'] ? 'build' : null;
+  if (buildScript) {
+    steps.push({ step: 'build', cmd: buildRunCommand(pm, buildScript) });
+  }
+
+  // Test: prefer test:ci, then test
+  const testScript = scripts['test:ci'] ? 'test:ci' : scripts['test'] ? 'test' : null;
+  if (testScript) {
+    steps.push({ step: 'test', cmd: buildRunCommand(pm, testScript) });
+  }
+
+  return steps;
+}
+
+// ============================================================================
+// Rust Discovery
+// ============================================================================
+
+/**
+ * Discover Rust commands from Cargo.toml presence
+ */
+async function discoverRustCommands(
+  $: BunShell,
+  directory: string,
+  includeClippy: boolean
+): Promise<CommandStep[]> {
+  if (!(await fileExists($, `${directory}/Cargo.toml`))) return [];
+
+  const steps: CommandStep[] = [{ step: 'lint (fmt)', cmd: 'cargo fmt --check' }];
+
+  if (includeClippy) {
+    steps.push({
+      step: 'lint (clippy)',
+      cmd: 'cargo clippy --all-targets --all-features',
+    });
+  }
+
+  steps.push({ step: 'build', cmd: 'cargo build' });
+  steps.push({ step: 'test', cmd: 'cargo test' });
+
+  return steps;
+}
+
+// ============================================================================
+// Go Discovery
+// ============================================================================
+
+/**
+ * Discover Go commands from go.mod presence
+ */
+async function discoverGoCommands($: BunShell, directory: string): Promise<CommandStep[]> {
+  if (!(await fileExists($, `${directory}/go.mod`))) return [];
+
+  return [{ step: 'test', cmd: 'go test ./...' }];
+}
+
+// ============================================================================
+// Python Discovery
+// ============================================================================
+
+/**
+ * Discover Python test commands with strong signal detection
+ */
+async function discoverPythonCommands($: BunShell, directory: string): Promise<CommandStep[]> {
+  // Only add pytest if we have strong signal
+  const hasPytestIni = await fileExists($, `${directory}/pytest.ini`);
+  const hasPyproject = await fileExists($, `${directory}/pyproject.toml`);
+
+  if (!hasPytestIni && !hasPyproject) return [];
+
+  // pytest.ini is strong signal
+  if (hasPytestIni) {
+    return [{ step: 'test', cmd: 'pytest' }];
+  }
+
+  // Check if pyproject.toml mentions pytest
+  if (hasPyproject) {
+    try {
+      const result = await $`cat ${directory}/pyproject.toml`.quiet();
+      const content = result.text();
+      if (content.includes('pytest')) {
+        return [{ step: 'test', cmd: 'pytest' }];
+      }
+    } catch {
+      // Ignore read errors - return empty array if file can't be read
+    }
+  }
+
+  return [];
+}
+
+// ============================================================================
+// Main Resolution Logic
+// ============================================================================
+
+/**
+ * Resolve the command plan based on configuration and discovery.
+ *
+ * Resolution order:
+ * 1. Configured commands (qualityGate.lint/build/test) - highest priority
+ * 2. management/ci.sh (Feature Factory convention) - only if no configured commands
+ * 3. Conventional discovery (Node/Rust/Go/Python) - only if no ci.sh
+ *
+ * @returns Array of command steps to execute, or empty if nothing found
+ */
+export async function resolveCommands(args: {
+  $: BunShell;
+  directory: string;
+  config: QualityGateConfig;
+}): Promise<CommandStep[]> {
+  const { $, directory, config } = args;
+  const mergedConfig = { ...DEFAULT_QUALITY_GATE, ...config };
+
+  // 1. Configured commands take priority (do NOT run ci.sh if these exist)
+  if (hasConfiguredCommands(config)) {
+    const steps: CommandStep[] = [];
+    const order = mergedConfig.steps;
+
+    for (const stepName of order) {
+      const cmd = config[stepName];
+      if (cmd) {
+        steps.push({ step: stepName, cmd });
+      }
+    }
+
+    return steps;
+  }
+
+  // 2. Feature Factory CI script (only if no configured commands)
+  if (mergedConfig.useCiSh !== 'never') {
+    const ciShPath = `${directory}/management/ci.sh`;
+    if (await fileExists($, ciShPath)) {
+      return [{ step: 'ci', cmd: `bash ${ciShPath}` }];
+    }
+  }
+
+  // 3. Conventional discovery (only if no ci.sh)
+  const pm = await detectPackageManager($, directory, mergedConfig.packageManager);
+
+  // Try Node first (most common)
+  if (await fileExists($, `${directory}/package.json`)) {
+    const nodeSteps = await discoverNodeCommands($, directory, pm);
+    if (nodeSteps.length > 0) return nodeSteps;
+  }
+
+  // Rust
+  const rustSteps = await discoverRustCommands(
+    $,
+    directory,
+    mergedConfig.include?.rustClippy ?? true
+  );
+  if (rustSteps.length > 0) return rustSteps;
+
+  // Go
+  const goSteps = await discoverGoCommands($, directory);
+  if (goSteps.length > 0) return goSteps;
+
+  // Python
+  const pythonSteps = await discoverPythonCommands($, directory);
+  if (pythonSteps.length > 0) return pythonSteps;
+
+  // No commands discovered
+  return [];
+}

package/src/index.ts

@@ -1,8 +1,9 @@
-import type { Plugin } from '@opencode-ai/plugin';
+import type { Plugin, Hooks } from '@opencode-ai/plugin';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { mkdir, access, writeFile, readFile } from 'node:fs/promises';
 import { constants as fsConstants } from 'node:fs';
+import { createQualityGateHooks } from './stop-quality-gate';
 
 /**
  * List of agent templates to sync to projects.
@@ -89,10 +90,45 @@ async function ensureAgentsInstalled(
   return { installed, updated };
 }
 
+/**
+ * Merge multiple hook objects into a single hooks object.
+ * For event handlers, chains them to run sequentially.
+ */
+function mergeHooks(...hookSets: Partial<Hooks>[]): Hooks {
+  const merged: Hooks = {};
+
+  for (const hooks of hookSets) {
+    for (const [key, handler] of Object.entries(hooks)) {
+      if (!handler) continue;
+
+      const existingHandler = merged[key as keyof Hooks];
+      if (existingHandler) {
+        // Chain handlers - run existing first, then new
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        merged[key as keyof Hooks] = (async (...args: any[]) => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          await (existingHandler as (...args: any[]) => Promise<void>)(...args);
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          await (handler as (...args: any[]) => Promise<void>)(...args);
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        }) as any;
+      } else {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        merged[key as keyof Hooks] = handler as any;
+      }
+    }
+  }
+
+  return merged;
+}
+
 /**
  * Feature Factory OpenCode Plugin
  *
- * This plugin automatically syncs Feature Factory agent templates to projects.
+ * This plugin automatically syncs Feature Factory agent templates to projects
+ * and runs quality gate checks when the agent becomes idle.
+ *
+ * ## Agent Templates
  *
  * Agents installed:
  * - ff-plan (primary): Creates detailed implementation plans
@@ -107,12 +143,26 @@ async function ensureAgentsInstalled(
  * - ff-ci (subagent): CI checks (tests, build, lint, type-check)
  * - ff-validate (subagent): Orchestrates all validation agents in parallel
  *
+ * ## Quality Gate (StopQualityGate)
+ *
+ * Runs quality checks when the agent becomes idle after editing files.
+ *
+ * Resolution order for commands:
+ * 1. opencode.json / .opencode/opencode.json `qualityGate` config (authoritative)
+ * 2. management/ci.sh (Feature Factory convention, replaces all steps)
+ * 3. Conventional discovery (Node/Rust/Go/Python)
+ *
  * Behavior:
  * - On plugin init (every OpenCode startup), syncs agents to .opencode/agent/
  * - Always overwrites existing files with bundled templates (user changes are not preserved)
  * - Also syncs on installation.updated event
+ * - Runs quality gate on session.idle (when agent finishes working)
+ * - Marks session dirty when edit/write/patch tools are used
+ * - On failure: prompts agent with failure output and instructions to fix
+ * - On success: logs "Quality gate passed."
  */
-export const FeatureFactoryPlugin: Plugin = async ({ worktree, directory }) => {
+export const FeatureFactoryPlugin: Plugin = async (input) => {
+  const { worktree, directory } = input;
   const rootDir = resolveRootDir({ worktree, directory });
 
   // Skip if no valid directory (e.g., global config with no project)
@@ -127,7 +177,16 @@ export const FeatureFactoryPlugin: Plugin = async ({ worktree, directory }) => {
     // Silent autosync shouldn't crash OpenCode startup
   }
 
-  return {
+  // Create quality gate hooks
+  let qualityGateHooks: Partial<Hooks> = {};
+  try {
+    qualityGateHooks = await createQualityGateHooks(input);
+  } catch {
+    // Silent failure - quality gate shouldn't crash OpenCode startup
+  }
+
+  // Agent sync hooks
+  const agentSyncHooks: Partial<Hooks> = {
     // Also sync on installation updates (plugin updates)
     event: async ({ event }) => {
       if (event.type === 'installation.updated') {
@@ -139,7 +198,19 @@ export const FeatureFactoryPlugin: Plugin = async ({ worktree, directory }) => {
       }
     },
   };
+
+  // Merge all hooks together
+  return mergeHooks(agentSyncHooks, qualityGateHooks);
 };
 
 // Default export for OpenCode plugin discovery
 export default FeatureFactoryPlugin;
+
+// Export types for consumers who want to use them
+export type {
+  QualityGateConfig,
+  CommandStep,
+  StepResult,
+  SessionState,
+  PackageManager,
+} from './types';

package/src/output.ts

@@ -0,0 +1,55 @@
+/**
+ * Regex pattern for detecting error-like lines in command output
+ */
+const ERROR_PATTERNS =
+  /(error|failed|failure|panic|assert|exception|traceback|TypeError|ReferenceError|SyntaxError|FAILED|FAIL|ERR!)/i;
+
+/**
+ * Extract lines that likely contain error information from command output.
+ * Includes 1-2 lines of context after each error line.
+ *
+ * @param output - The command output to search
+ * @param maxLines - Maximum number of error lines to extract
+ * @returns Array of error-like lines (up to maxLines)
+ */
+export function extractErrorLines(output: string, maxLines: number): string[] {
+  const lines = output.split('\n');
+  const errorLines: string[] = [];
+
+  for (let i = 0; i < lines.length && errorLines.length < maxLines; i++) {
+    const line = lines[i];
+    if (line && ERROR_PATTERNS.test(line)) {
+      errorLines.push(line);
+      // Include 1-2 lines of context after the error
+      const nextLine = lines[i + 1];
+      const nextNextLine = lines[i + 2];
+      if (nextLine !== undefined) {
+        errorLines.push(nextLine);
+      }
+      if (nextNextLine !== undefined) {
+        errorLines.push(nextNextLine);
+      }
+    }
+  }
+
+  return errorLines.slice(0, maxLines);
+}
+
+/**
+ * Return the last N lines of output, with a truncation notice if needed.
+ *
+ * @param output - The full command output
+ * @param maxLines - Maximum number of lines to return
+ * @returns Truncated output with notice, or full output if short enough
+ */
+export function tailLines(output: string, maxLines: number): string {
+  const lines = output.split('\n');
+  if (lines.length <= maxLines) {
+    return output;
+  }
+
+  const truncatedCount = lines.length - maxLines;
+  const tail = lines.slice(-maxLines).join('\n');
+
+  return `... (${truncatedCount} lines truncated)\n${tail}`;
+}

package/src/quality-gate-config.ts

@@ -0,0 +1,108 @@
+import type { QualityGateConfig } from './types';
+
+/**
+ * Default configuration values for StopQualityGate
+ */
+export const DEFAULT_QUALITY_GATE: Required<
+  Omit<QualityGateConfig, 'lint' | 'build' | 'test' | 'cwd'>
+> = {
+  steps: ['lint', 'build', 'test'],
+  useCiSh: 'auto',
+  packageManager: 'auto',
+  cacheSeconds: 30,
+  maxOutputLines: 160,
+  maxErrorLines: 60,
+  include: {
+    rustClippy: true,
+  },
+};
+
+// Shell type - uses `any` to be compatible with OpenCode's BunShell
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type BunShell = any;
+
+/**
+ * Read a JSON file safely, returning null if not found or invalid
+ */
+export async function readJsonFile(
+  $: BunShell,
+  path: string
+): Promise<Record<string, unknown> | null> {
+  try {
+    const result = await $`cat ${path}`.quiet();
+    return JSON.parse(result.text()) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a file exists
+ */
+export async function fileExists($: BunShell, path: string): Promise<boolean> {
+  try {
+    await $`test -f ${path}`.quiet();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Merge two qualityGate config objects.
+ *
+ * Precedence: `.opencode/opencode.json` overrides `opencode.json` (root).
+ * Deep-merges nested objects like `include`.
+ */
+export function mergeQualityGateConfig(
+  root: QualityGateConfig | undefined,
+  dotOpencode: QualityGateConfig | undefined
+): QualityGateConfig {
+  const base = root ?? {};
+  const override = dotOpencode ?? {};
+
+  return {
+    ...base,
+    ...override,
+    // Deep merge the `include` object
+    include: {
+      ...(base.include ?? {}),
+      ...(override.include ?? {}),
+    },
+  };
+}
+
+/**
+ * Load and merge qualityGate config from both config file locations.
+ *
+ * Reads from:
+ * - `${directory}/opencode.json`
+ * - `${directory}/.opencode/opencode.json`
+ *
+ * Merges ONLY the `qualityGate` key. `.opencode/opencode.json` takes precedence.
+ */
+export async function loadQualityGateConfig(
+  $: BunShell,
+  directory: string
+): Promise<QualityGateConfig> {
+  const rootConfigPath = `${directory}/opencode.json`;
+  const dotOpencodeConfigPath = `${directory}/.opencode/opencode.json`;
+
+  const [rootJson, dotOpencodeJson] = await Promise.all([
+    readJsonFile($, rootConfigPath),
+    readJsonFile($, dotOpencodeConfigPath),
+  ]);
+
+  const rootQualityGate = rootJson?.qualityGate as QualityGateConfig | undefined;
+  const dotOpencodeQualityGate = dotOpencodeJson?.qualityGate as QualityGateConfig | undefined;
+
+  return mergeQualityGateConfig(rootQualityGate, dotOpencodeQualityGate);
+}
+
+/**
+ * Check if any explicit commands are configured (lint/build/test).
+ * If so, these take priority over ci.sh and discovery.
+ */
+export function hasConfiguredCommands(config: QualityGateConfig): boolean {
+  return !!(config.lint || config.build || config.test);
+}

package/src/stop-quality-gate.ts

@@ -0,0 +1,394 @@
+import type { PluginInput, Hooks } from '@opencode-ai/plugin';
+import type { QualityGateConfig, SessionState, StepResult } from './types';
+import { DEFAULT_QUALITY_GATE, loadQualityGateConfig } from './quality-gate-config';
+import { extractErrorLines, tailLines } from './output';
+import { resolveCommands } from './discovery';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const SERVICE_NAME = 'feature-factory';
+
+/** Debounce delay before running quality gate after session.idle (ms) */
+const IDLE_DEBOUNCE_MS = 500;
+
+// ============================================================================
+// Session State Management
+// ============================================================================
+
+interface ExtendedSessionState extends SessionState {
+  /** Whether quality gate has passed since last edit */
+  qualityGatePassed: boolean;
+  /** Debounce timer for session.idle */
+  idleDebounce: ReturnType<typeof setTimeout> | null;
+}
+
+const sessions = new Map<string, ExtendedSessionState>();
+
+function getSessionState(sessionId: string): ExtendedSessionState {
+  const existing = sessions.get(sessionId);
+  if (existing) return existing;
+
+  const state: ExtendedSessionState = {
+    lastRunAt: 0,
+    lastResults: [],
+    dirty: true,
+    qualityGatePassed: false,
+    idleDebounce: null,
+  };
+  sessions.set(sessionId, state);
+  return state;
+}
+
+// ============================================================================
+// Prompt Builders
+// ============================================================================
+
+/**
+ * Build the prompt shown when a quality gate step fails
+ */
+function buildFailurePrompt(params: { config: QualityGateConfig; failed: StepResult }): string {
+  const merged = { ...DEFAULT_QUALITY_GATE, ...params.config };
+  const errorLines = extractErrorLines(params.failed.output, merged.maxErrorLines);
+  const tailOutput = tailLines(params.failed.output, merged.maxOutputLines);
+
+  let prompt = `## Quality gate failed: ${params.failed.step}
+
+The quality gate check has failed. Please fix the issues before completing your work.
+
+**Command:**
+\`\`\`
+${params.failed.cmd}
+\`\`\`
+
+**Exit code:** ${params.failed.exitCode}
+`;
+
+  if (errorLines.length > 0) {
+    prompt += `
+**Key errors:**
+\`\`\`
+${errorLines.join('\n')}
+\`\`\`
+`;
+  }
+
+  prompt += `
+**Output (tail):**
+\`\`\`
+${tailOutput}
+\`\`\`
+
+## Next steps:
+1. Fix the issues reported above.
+2. Re-run: \`${params.failed.cmd}\`
+3. Complete your work.
+`;
+
+  return prompt;
+}
+
+/**
+ * Build the prompt shown when no quality gate commands could be found
+ */
+function buildNoCommandsPrompt(params: { directory: string }): string {
+  return `## Quality gate could not run
+
+No quality commands were found for this project.
+
+**Checked locations:**
+- \`${params.directory}/opencode.json\` (qualityGate.lint/build/test)
+- \`${params.directory}/.opencode/opencode.json\` (qualityGate.lint/build/test)
+- \`${params.directory}/management/ci.sh\` (Feature Factory CI script)
+- \`${params.directory}/package.json\` (npm scripts: lint, build, test)
+- \`${params.directory}/Cargo.toml\` (Rust project)
+- \`${params.directory}/go.mod\` (Go project)
+- \`${params.directory}/pyproject.toml\` or \`pytest.ini\` (Python project)
+
+**To configure quality gates, either:**
+1. Add \`qualityGate\` config to \`opencode.json\` or \`.opencode/opencode.json\`:
+   \`\`\`json
+   {
+     "qualityGate": {
+       "lint": "npm run lint",
+       "build": "npm run build",
+       "test": "npm run test"
+     }
+   }
+   \`\`\`
+
+2. Or create a Feature Factory CI script at \`management/ci.sh\``;
+}
+
+// ============================================================================
+// Command Execution
+// ============================================================================
+
+// Shell type from PluginInput
+type BunShell = PluginInput['$'];
+type Client = PluginInput['client'];
+
+/**
+ * Run a single command and capture its output
+ */
+async function runCommand(
+  $: BunShell,
+  cmd: string,
+  cwd: string
+): Promise<{ exitCode: number; output: string }> {
+  try {
+    const result = await $`bash -c ${cmd}`.cwd(cwd).quiet().nothrow();
+    const stdout = result.text() || '';
+    const stderr = result.stderr?.toString?.() || '';
+    return {
+      exitCode: result.exitCode,
+      output: stdout + stderr,
+    };
+  } catch (err: unknown) {
+    const error = err as { exitCode?: number; message?: string };
+    return {
+      exitCode: error.exitCode ?? 1,
+      output: error.message || String(err),
+    };
+  }
+}
+
+/**
+ * Run all command steps sequentially, stopping on first failure
+ */
+async function runAllCommands(
+  $: BunShell,
+  steps: { step: string; cmd: string }[],
+  cwd: string
+): Promise<StepResult[]> {
+  const results: StepResult[] = [];
+
+  for (const { step, cmd } of steps) {
+    const { exitCode, output } = await runCommand($, cmd, cwd);
+    results.push({ step, cmd, exitCode, output });
+
+    // Stop on first failure
+    if (exitCode !== 0) break;
+  }
+
+  return results;
+}
+
+// ============================================================================
+// Logging Helper
+// ============================================================================
+
+/**
+ * Log a message using the OpenCode client API
+ */
+async function log(
+  client: Client,
+  level: 'debug' | 'info' | 'warn' | 'error',
+  message: string,
+  extra?: Record<string, unknown>
+): Promise<void> {
+  try {
+    await client.app.log({
+      body: {
+        service: SERVICE_NAME,
+        level,
+        message,
+        extra,
+      },
+    });
+  } catch {
+    // Silently ignore logging errors to avoid breaking the plugin
+    return undefined;
+  }
+}
+
+// ============================================================================
+// Quality Gate Hooks Factory
+// ============================================================================
+
+/**
+ * Create quality gate hooks for the plugin.
+ *
+ * Resolution order for commands:
+ * 1. opencode.json / .opencode/opencode.json `qualityGate` config (authoritative)
+ * 2. management/ci.sh (Feature Factory convention, replaces all steps)
+ * 3. Conventional discovery (Node/Rust/Go/Python)
+ *
+ * On failure: prompts agent with failure output and instructions to fix.
+ * On success: logs "Quality gate passed."
+ * If no commands found: logs warning about missing configuration.
+ */
+export async function createQualityGateHooks(input: PluginInput): Promise<Partial<Hooks>> {
+  const { client, $, directory } = input;
+
+  // Load and merge config from both config file locations
+  const qualityGate = await loadQualityGateConfig($, directory);
+
+  const cacheSeconds = qualityGate.cacheSeconds ?? DEFAULT_QUALITY_GATE.cacheSeconds;
+  const cwd = qualityGate.cwd ? `${directory}/${qualityGate.cwd}` : directory;
+
+  /**
+   * Run the quality gate checks for a session
+   */
+  async function runQualityGate(sessionId: string): Promise<void> {
+    const state = getSessionState(sessionId);
+    const now = Date.now();
+    const cacheExpired = now - state.lastRunAt > cacheSeconds * 1000;
+
+    // Skip if already passed and not dirty
+    if (state.qualityGatePassed && !state.dirty && !cacheExpired) {
+      await log(client, 'debug', 'quality-gate.skipped (cached pass)', { sessionId });
+      return;
+    }
+
+    // Log start
+    await log(client, 'info', 'quality-gate.started', {
+      sessionId,
+      directory,
+      cwd,
+    });
+
+    // Resolve commands
+    const plan = await resolveCommands({ $, directory, config: qualityGate });
+
+    // No commands found - log warning but don't block
+    if (plan.length === 0) {
+      await log(client, 'warn', 'quality-gate.no_commands', {
+        sessionId,
+        directory,
+      });
+
+      // Only prompt once per session about missing config
+      if (!state.qualityGatePassed) {
+        await client.session.prompt({
+          path: { id: sessionId },
+          body: {
+            parts: [{ type: 'text', text: buildNoCommandsPrompt({ directory }) }],
+          },
+        });
+      }
+      return;
+    }
+
+    // Run commands if dirty, cache expired, or no cached results
+    let results: StepResult[] = state.lastResults;
+
+    if (state.dirty || cacheExpired || results.length === 0) {
+      const startTime = Date.now();
+      results = await runAllCommands($, plan, cwd);
+      const durationMs = Date.now() - startTime;
+
+      state.lastResults = results;
+      state.lastRunAt = now;
+      state.dirty = false;
+
+      // Log execution details
+      await log(client, 'debug', 'quality-gate.executed', {
+        sessionId,
+        plan: plan.map((p) => p.step),
+        durationMs,
+        results: results.map((r) => ({
+          step: r.step,
+          exitCode: r.exitCode,
+        })),
+      });
+    }
+
+    // Check for failures
+    const failed = results.find((r) => r.exitCode !== 0);
+
+    if (failed) {
+      state.qualityGatePassed = false;
+
+      // Log failure
+      await log(client, 'error', 'quality-gate.failed', {
+        sessionId,
+        step: failed.step,
+        cmd: failed.cmd,
+        exitCode: failed.exitCode,
+        outputTail: tailLines(failed.output, 50),
+      });
+
+      // Prompt agent with failure details to continue working
+      await client.session.prompt({
+        path: { id: sessionId },
+        body: {
+          parts: [
+            {
+              type: 'text',
+              text: buildFailurePrompt({ config: qualityGate, failed }),
+            },
+          ],
+        },
+      });
+      return;
+    }
+
+    // All passed
+    state.qualityGatePassed = true;
+
+    await log(client, 'info', 'quality-gate.passed', {
+      sessionId,
+      steps: results.map((r) => r.step),
+    });
+  }
+
+  return {
+    // Handle session lifecycle and idle events
+    event: async ({ event }) => {
+      // Event properties contain sessionID
+      const eventProps = (event as { properties?: { sessionID?: string } }).properties;
+      const sessionId = eventProps?.sessionID;
+
+      if (event.type === 'session.created' && sessionId) {
+        sessions.set(sessionId, {
+          lastRunAt: 0,
+          lastResults: [],
+          dirty: true,
+          qualityGatePassed: false,
+          idleDebounce: null,
+        });
+        await log(client, 'debug', 'session.created', { sessionId });
+      }
+
+      if (event.type === 'session.deleted' && sessionId) {
+        const state = sessions.get(sessionId);
+        if (state?.idleDebounce) {
+          clearTimeout(state.idleDebounce);
+        }
+        sessions.delete(sessionId);
+        await log(client, 'debug', 'session.deleted', { sessionId });
+      }
+
+      // Run quality gate when session becomes idle (agent stopped)
+      if (event.type === 'session.idle' && sessionId) {
+        const state = getSessionState(sessionId);
+
+        // Debounce to avoid running multiple times
+        if (state.idleDebounce) {
+          clearTimeout(state.idleDebounce);
+        }
+
+        state.idleDebounce = setTimeout(async () => {
+          state.idleDebounce = null;
+          await runQualityGate(sessionId);
+        }, IDLE_DEBOUNCE_MS);
+      }
+    },
+
+    // Mark session dirty when files are edited
+    'tool.execute.before': async (input) => {
+      const sessionId = input.sessionID;
+      if (!sessionId) return;
+
+      const state = getSessionState(sessionId);
+
+      if (input.tool === 'edit' || input.tool === 'write' || input.tool === 'patch') {
+        state.dirty = true;
+        state.qualityGatePassed = false;
+        await log(client, 'debug', 'session.dirty', { sessionId, tool: input.tool });
+      }
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,72 @@
+/**
+ * Configuration for the StopQualityGate plugin.
+ * Read from `qualityGate` in opencode.json or .opencode/opencode.json
+ */
+export interface QualityGateConfig {
+  /** Custom lint command (e.g., "pnpm -s lint") */
+  lint?: string;
+  /** Custom build command (e.g., "pnpm -s build") */
+  build?: string;
+  /** Custom test command (e.g., "pnpm -s test") */
+  test?: string;
+  /** Working directory relative to repo root (default: ".") */
+  cwd?: string;
+  /** Order of steps to run (default: ["lint", "build", "test"]) */
+  steps?: ('lint' | 'build' | 'test')[];
+  /** Whether to use management/ci.sh: "auto" | "always" | "never" (default: "auto") */
+  useCiSh?: 'auto' | 'always' | 'never';
+  /** Package manager override: "auto" | "pnpm" | "bun" | "yarn" | "npm" (default: "auto") */
+  packageManager?: 'auto' | 'pnpm' | 'bun' | 'yarn' | 'npm';
+  /** Cache duration in seconds before re-running checks (default: 30) */
+  cacheSeconds?: number;
+  /** Max lines of output tail to include in failure prompt (default: 160) */
+  maxOutputLines?: number;
+  /** Max error lines to extract and show (default: 60) */
+  maxErrorLines?: number;
+  /** Feature flags for discovery */
+  include?: {
+    /** Include cargo clippy in Rust discovery (default: true) */
+    rustClippy?: boolean;
+  };
+}
+
+/**
+ * A single command step to execute
+ */
+export interface CommandStep {
+  /** Name of the step (e.g., "lint", "build", "test", "ci") */
+  step: string;
+  /** The shell command to run */
+  cmd: string;
+}
+
+/**
+ * Result of executing a command step
+ */
+export interface StepResult {
+  /** Name of the step */
+  step: string;
+  /** The command that was run */
+  cmd: string;
+  /** Exit code (0 = success) */
+  exitCode: number;
+  /** Combined stdout + stderr output */
+  output: string;
+}
+
+/**
+ * Per-session state for caching and dirty tracking
+ */
+export interface SessionState {
+  /** Timestamp of last quality gate run */
+  lastRunAt: number;
+  /** Results from last run */
+  lastResults: StepResult[];
+  /** Whether files have been edited since last run */
+  dirty: boolean;
+}
+
+/**
+ * Package manager type for Node projects
+ */
+export type PackageManager = 'pnpm' | 'bun' | 'yarn' | 'npm';