@dezycro-ai/agent-plugin 2.0.0

package/dist/hooks/types.d.ts

@@ -0,0 +1,249 @@
+/**
+ * types.ts — shared type definitions for Companion V2 hooks.
+ *
+ * Hook output types match Claude Code's documented schema (captured from
+ * the schema error message hit in the V2.0 dogfood — Anthropic does not
+ * publish official TS types as of 2026-05). Hook input payload types are
+ * partials because Claude Code's payload shape varies per event and we
+ * only consume the fields we use.
+ *
+ * Companion state and config match the on-disk JSON shape in
+ * `.dezycro/companion-state.json` and `.dezycro/config.json`.
+ */
+export type HookEventName = 'PreToolUse' | 'PostToolUse' | 'UserPromptSubmit' | 'Stop' | 'SessionStart' | 'SessionEnd' | 'PreCompact' | 'Notification' | 'SubagentStop';
+export type Decision = 'approve' | 'block';
+export type PermissionDecision = 'allow' | 'deny' | 'ask' | 'defer';
+/** Fields valid at the top level of every hook output. */
+interface HookOutputCommon {
+    continue?: boolean;
+    suppressOutput?: boolean;
+    stopReason?: string;
+    decision?: Decision;
+    reason?: string;
+    systemMessage?: string;
+    permissionDecision?: PermissionDecision;
+}
+/** PreToolUse: also accepts a hookSpecificOutput with PreToolUse fields. */
+export interface PreToolUseHookOutput extends HookOutputCommon {
+    hookSpecificOutput?: {
+        hookEventName: 'PreToolUse';
+        permissionDecision?: PermissionDecision;
+        permissionDecisionReason?: string;
+        updatedInput?: Record<string, unknown>;
+    };
+}
+/** PostToolUse: optional additionalContext to inject into the next turn. */
+export interface PostToolUseHookOutput extends HookOutputCommon {
+    hookSpecificOutput?: {
+        hookEventName: 'PostToolUse';
+        additionalContext?: string;
+    };
+}
+/** UserPromptSubmit: additionalContext REQUIRED if hookSpecificOutput is set. */
+export interface UserPromptSubmitHookOutput extends HookOutputCommon {
+    hookSpecificOutput?: {
+        hookEventName: 'UserPromptSubmit';
+        additionalContext: string;
+    };
+}
+/** Stop: no hookSpecificOutput. Only top-level fields are valid. */
+export type StopHookOutput = HookOutputCommon;
+/** SessionStart / SessionEnd / etc: top-level only (no hookSpecificOutput). */
+export type SessionStartHookOutput = HookOutputCommon;
+export type AnyHookOutput = PreToolUseHookOutput | PostToolUseHookOutput | UserPromptSubmitHookOutput | StopHookOutput | SessionStartHookOutput;
+export interface PreToolUsePayload {
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+    session_id?: string;
+    transcript_path?: string;
+}
+export interface PostToolUsePayload {
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+    tool_response?: Record<string, unknown>;
+    response?: Record<string, unknown>;
+    session_id?: string;
+    transcript_path?: string;
+}
+export interface UserPromptSubmitPayload {
+    prompt?: string;
+    user_message?: string;
+    message?: string;
+    session_id?: string;
+}
+export interface StopPayload {
+    session_id?: string;
+    transcript_path?: string;
+}
+export interface SessionStartPayload {
+    session_id?: string;
+}
+export interface ControllerEdit {
+    path: string;
+    editedTs: string;
+}
+export interface CoverageSnapshot {
+    uncoveredPaths?: number;
+    endpointsNotInSpec?: number;
+    staleBaselines?: number;
+    surfacedTs?: string | null;
+    previous?: CoverageSnapshot | null;
+    [extra: string]: unknown;
+}
+export interface LastAutoWorkbookMutation {
+    /** Bare tool name, e.g. "add_decision" / "update_task" (no mcp__ prefix). */
+    tool: string;
+    entityId: string | null;
+    createdInTurnId: number;
+    createdTs: string;
+    /** Only set for update_task — the status to restore on undo. */
+    priorStatus: string | null;
+}
+export interface CompanionMetrics {
+    autoDecisionLogs: number;
+    autoIssueLogs: number;
+    autoAssumptionLogs: number;
+    autoTaskStatusLogs: number;
+    undoCount: number;
+    verifyAutoRuns: number;
+    verifyAutoFailures: number;
+    qualityGateFailures: number;
+    contextGateFailures: number;
+    lockContention: number;
+    forceApprovals: number;
+}
+export interface CompanionState {
+    schemaVersion: number;
+    currentSessionId: string | null;
+    authoringMode: boolean;
+    authoringDocId: string | null;
+    authoringDocType: 'PRD' | 'TRD' | null;
+    authoringTranscriptPath: string | null;
+    authoringStartedTs: string | null;
+    pulseCount: number;
+    lastEditTs: string | null;
+    needsSpecPublish: boolean;
+    controllerEditsSinceLastPublish: ControllerEdit[];
+    coverageSnapshot: CoverageSnapshot | null;
+    coverageSnapshotTs: string | null;
+    coverageFetchPending: boolean;
+    lastVerifyCompletionTs: string | null;
+    recentDecisionHashes: string[];
+    recentIssueHashes: string[];
+    recentAssumptionHashes: string[];
+    lastAutoWorkbookMutation: LastAutoWorkbookMutation | null;
+    sessionAutoLogCount: number;
+    turnAutoLogCount: number;
+    currentTurnId: number;
+    suppressWorkbookUpdatesUntil: string | null;
+    pendingWorkbookSweep: boolean;
+    pendingWorkbookSweepReason: string | null;
+    lastSeenVerifyCompletionTs: string | null;
+    metrics: CompanionMetrics;
+}
+/**
+ * Patch shape for state.patch() — partial state + convenience "push" keys
+ * that append to the corresponding ring buffer instead of replacing it.
+ * `metrics` overrides the full-CompanionState definition to be partial.
+ */
+export type StatePatch = Partial<Omit<CompanionState, 'metrics'>> & {
+    metrics?: Partial<CompanionMetrics>;
+    pushDecisionHash?: string;
+    pushIssueHash?: string;
+    pushAssumptionHash?: string;
+    pushControllerEdit?: ControllerEdit;
+};
+export interface PostEditPulseConfig {
+    enabled?: boolean;
+    threshold?: number;
+}
+export interface AutoVerifyConfig {
+    preTaskDone?: boolean;
+    prePush?: boolean;
+    postEditPulse?: PostEditPulseConfig;
+    autoPublishSpecOnControllerChange?: boolean;
+    controllerPaths?: string[];
+    verifyTimeoutSeconds?: number;
+    publishSpecTimeoutSeconds?: number;
+}
+export interface ThresholdOverrides {
+    decision?: number | null;
+    issue?: number | null;
+    assumption?: number | null;
+    taskStatus?: number | null;
+}
+export type PresetName = 'conservative' | 'balanced' | 'aggressive';
+export interface AutoWorkbookUpdatesConfig {
+    enabled?: boolean;
+    preset?: PresetName;
+    maxAutoLogsPerTurn?: number;
+    maxAutoLogsPerSession?: number;
+    undoWindow?: 'next-turn' | string;
+    thresholds?: ThresholdOverrides;
+    trivialTurnCharCutoff?: number;
+    hashRingBufferSize?: number;
+}
+export interface CoverageNudgesConfig {
+    enabled?: boolean;
+    staleBaselineDays?: number;
+    fetchMode?: 'async' | 'sync' | 'off';
+}
+export interface AuthoringConfig {
+    defaultDepth?: 'adaptive' | 'shallow' | 'deep';
+    existingWorkScan?: boolean;
+    qualityGate?: {
+        enabled?: boolean;
+    };
+    minViableContextGate?: {
+        enabled?: boolean;
+    };
+}
+export interface CompanionConfig {
+    companion?: {
+        autoVerify?: AutoVerifyConfig;
+        autoWorkbookUpdates?: AutoWorkbookUpdatesConfig;
+        coverageNudges?: CoverageNudgesConfig;
+        authoring?: AuthoringConfig;
+        safeMode?: boolean;
+    };
+}
+export interface Thresholds {
+    decision: number;
+    issue: number;
+    assumption: number;
+    taskStatus: number;
+}
+export interface ActiveFeature {
+    featureId: string | null;
+    featureName: string | null;
+}
+export interface SweepDirectiveOpts {
+    thresholds: Thresholds;
+    perTurnSlotsLeft: number;
+    perSessionSlotsLeft: number;
+    recentHashes: string[];
+    activeFeatureId: string | null;
+    activeFeatureName: string | null;
+}
+export interface ReversalDirective {
+    tool: 'update_decision' | 'update_issue' | 'update_task';
+    args: Record<string, unknown>;
+    humanLine: string;
+}
+export type HookEvent = 'session-start' | 'user-prompt-submit' | 'pre-tool-use' | 'post-tool-use' | 'stop' | 'state' | 'authoring-state';
+export interface RouterInvocation {
+    event: HookEvent | null;
+    route: string | null;
+    payload: unknown;
+    flags: Record<string, string | boolean>;
+}
+export interface QualityGateBlockingIssue {
+    section: string;
+    issue: string;
+    required_fix: string;
+}
+export interface QualityGateResult {
+    passed: boolean;
+    blockingIssues: QualityGateBlockingIssue[];
+}
+export {};

package/dist/hooks/types.js

@@ -0,0 +1,14 @@
+/**
+ * types.ts — shared type definitions for Companion V2 hooks.
+ *
+ * Hook output types match Claude Code's documented schema (captured from
+ * the schema error message hit in the V2.0 dogfood — Anthropic does not
+ * publish official TS types as of 2026-05). Hook input payload types are
+ * partials because Claude Code's payload shape varies per event and we
+ * only consume the fields we use.
+ *
+ * Companion state and config match the on-disk JSON shape in
+ * `.dezycro/companion-state.json` and `.dezycro/config.json`.
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });

package/hooks/companion-runner

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * companion-runner — single entry point for all Dezycro Companion hooks.
+ *
+ * Invocation contract (TRD §4.2):
+ *   companion-runner <event> [--route=<route>] [--flag[=value] ...]
+ *
+ * where <event> is one of:
+ *   session-start | user-prompt-submit | pre-tool-use | post-tool-use | stop
+ *   | state | authoring-state
+ *
+ * Reads the hook payload from stdin (JSON, when applicable), dispatches to
+ * lib/router.js, and exits with the appropriate status code / stdout payload
+ * per Claude Code's hook contract.
+ *
+ * Live routes:
+ *   - `pre-tool-use --route=update_task`              (pillar 1; TRD §5.1)
+ *   - `pre-tool-use --route=change_document_status`   (pillar 5; TRD §5.5.3)
+ *   - `post-tool-use --route=edit`                    (pillars 1+2; TRD §5.1+§5.2)
+ *
+ * Top-level skill-facing subcommands (`state`, `authoring-state`) do NOT read
+ * stdin — they're invoked synchronously from skill markdown via the Bash tool.
+ *
+ * Other routes exit 0 silently (no-op) so the runner can be wired up via
+ * settings.json without destabilizing existing sessions.
+ */
+
+'use strict';
+
+const router = require('../dist/hooks/lib/router');
+
+const SKILL_INVOKED_SUBCOMMANDS = new Set(['state', 'authoring-state']);
+
+function parseArgv(argv) {
+  const positional = [];
+  let route = null;
+  const flags = {};
+  // argv[0] = node, argv[1] = this script
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--route=')) {
+      route = arg.slice('--route='.length);
+    } else if (arg === '--route') {
+      route = argv[++i] || null;
+    } else if (arg.startsWith('--')) {
+      // Generic flag parsing: --key=value OR --key (boolean true).
+      const body = arg.slice(2);
+      const eq = body.indexOf('=');
+      if (eq >= 0) {
+        flags[body.slice(0, eq)] = body.slice(eq + 1);
+      } else {
+        flags[body] = true;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  const event = positional[0] || null;
+  return { event, route, flags };
+}
+
+async function readStdin() {
+  if (process.stdin.isTTY) return null;
+  return new Promise((resolve) => {
+    let data = '';
+    let resolved = false;
+    const finish = () => {
+      if (resolved) return;
+      resolved = true;
+      if (!data.trim()) return resolve(null);
+      try {
+        resolve(JSON.parse(data));
+      } catch (_err) {
+        resolve(null);
+      }
+    };
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', finish);
+    process.stdin.on('error', finish);
+    // Hard ceiling so we never hang.
+    setTimeout(finish, 250);
+  });
+}
+
+(async function main() {
+  try {
+    const { event, route, flags } = parseArgv(process.argv);
+    if (!event) {
+      // Unknown invocation; exit silently rather than spam stderr.
+      process.exit(0);
+    }
+    // Skill-facing subcommands are invoked synchronously via the Bash tool and
+    // don't carry a stdin payload — skip the read so we don't burn 250ms
+    // waiting on a pipe that isn't there.
+    const skipStdin = SKILL_INVOKED_SUBCOMMANDS.has(event);
+    const payload = skipStdin ? null : await readStdin();
+    const code = await router.dispatch({ event, route, payload, flags });
+    process.exit(typeof code === 'number' ? code : 0);
+  } catch (_err) {
+    // Per TRD §4.1: per-route try/catch boundaries. A runner crash must never
+    // break the user's session — exit 0 and rely on lib/logging.js for
+    // diagnostics in real routes.
+    process.exit(0);
+  }
+})();

package/hooks/hooks.json

@@ -0,0 +1,74 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/companion-runner session-start"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/companion-runner user-prompt-submit"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "mcp__dezycro__update_task|mcp__dezycro-dev__update_task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/companion-runner pre-tool-use --route=update_task"
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__dezycro__change_document_status|mcp__dezycro-dev__change_document_status",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/companion-runner pre-tool-use --route=change_document_status"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/companion-runner post-tool-use --route=edit"
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__dezycro__add_decision|mcp__dezycro-dev__add_decision|mcp__dezycro__add_issue|mcp__dezycro-dev__add_issue|mcp__dezycro__add_assumption|mcp__dezycro-dev__add_assumption|mcp__dezycro__update_task|mcp__dezycro-dev__update_task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/companion-runner post-tool-use --route=workbook_mutation"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/companion-runner stop"
+          }
+        ]
+      }
+    ]
+  }
+}

package/install.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const HOME = os.homedir();
+const commandsDir = path.join(HOME, ".claude", "commands", "dezycro");
+const skillsDir = path.join(__dirname, "skills");
+const settingsPath = path.join(HOME, ".claude", "settings.json");
+const hooksJsonPath = path.join(__dirname, "hooks", "hooks.json");
+const runnerPath = path.join(__dirname, "hooks", "companion-runner");
+
+fs.mkdirSync(commandsDir, { recursive: true });
+
+const skills = fs
+  .readdirSync(skillsDir, { withFileTypes: true })
+  .filter((d) => d.isDirectory() && fs.existsSync(path.join(skillsDir, d.name, "SKILL.md")))
+  .map((d) => d.name);
+
+for (const name of skills) {
+  const src = path.join(skillsDir, name, "SKILL.md");
+  const dst = path.join(commandsDir, `${name}.md`);
+  fs.copyFileSync(src, dst);
+}
+
+let hooksInstalled = false;
+let hooksAlreadyPresent = false;
+try {
+  const hooksConfig = JSON.parse(fs.readFileSync(hooksJsonPath, "utf8"));
+  const incoming = inlinePluginRoot(hooksConfig.hooks || {}, __dirname);
+
+  let existing = { hooks: {} };
+  if (fs.existsSync(settingsPath)) {
+    try { existing = JSON.parse(fs.readFileSync(settingsPath, "utf8")); }
+    catch { existing = { hooks: {} }; }
+  }
+  if (!existing.hooks) existing.hooks = {};
+
+  const before = JSON.stringify(existing.hooks);
+  for (const event of Object.keys(incoming)) {
+    const existingEntries = Array.isArray(existing.hooks[event]) ? existing.hooks[event] : [];
+    const filtered = existingEntries.filter((e) => !isDezycroEntry(e));
+    existing.hooks[event] = [...filtered, ...incoming[event]];
+  }
+  const after = JSON.stringify(existing.hooks);
+
+  if (before === after) {
+    hooksAlreadyPresent = true;
+  } else {
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(existing, null, 2) + "\n");
+    hooksInstalled = true;
+  }
+
+  try { fs.chmodSync(runnerPath, 0o755); } catch {}
+} catch (err) {
+  console.log(`\n  ⚠ Could not install V2 hooks automatically: ${err.message}`);
+  console.log(`     Hooks config: ${hooksJsonPath}`);
+  console.log(`     Merge it into ${settingsPath} manually, or install as a Claude Code plugin.`);
+}
+
+console.log(`\n  ✓ Dezycro commands installed (${skills.length}) to ~/.claude/commands/dezycro/`);
+console.log(`     ${skills.map((s) => `/dezycro:${s}`).join(", ")}`);
+if (hooksInstalled) {
+  console.log(`  ✓ Companion V2 hooks merged into ~/.claude/settings.json`);
+} else if (hooksAlreadyPresent) {
+  console.log(`  ✓ Companion V2 hooks already present in ~/.claude/settings.json`);
+}
+console.log(`\n  Next: npx dezycro-setup`);
+console.log(`  Then: /dezycro:import-features\n`);
+
+function inlinePluginRoot(hooks, root) {
+  return JSON.parse(JSON.stringify(hooks, (k, v) => {
+    if (typeof v === "string") return v.replace(/"?\$\{CLAUDE_PLUGIN_ROOT\}"?/g, root);
+    return v;
+  }));
+}
+
+function isDezycroEntry(entry) {
+  if (!entry || typeof entry !== "object") return false;
+  const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+  return hooks.some((h) => h && typeof h.command === "string" && h.command.includes("/hooks/companion-runner"));
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@dezycro-ai/agent-plugin",
+  "version": "2.0.0",
+  "description": "Official Dezycro plugin for AI coding agents (Claude Code today, more to come) — reverse-engineer your codebase into features, PRDs, TRDs, and live verification.",
+  "bin": {
+    "dezycro-setup": "./setup.js",
+    "dezycro-resolve-auth": "./bin/resolve-auth.js"
+  },
+  "keywords": [
+    "dezycro",
+    "claude-code",
+    "ai-agents",
+    "prd",
+    "trd",
+    "verification"
+  ],
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://docs.dezycro.ai/claude-code/install/",
+  "bugs": {
+    "url": "https://docs.dezycro.ai/claude-code/install/"
+  },
+  "files": [
+    ".claude-plugin/**/*",
+    "dist/**/*",
+    "hooks/**/*",
+    "prompts/**/*",
+    "skills/**/*",
+    "bin/**/*",
+    "install.js",
+    "setup.js",
+    "README.md",
+    "PERSONAS.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "[ -d src ] && tsc || true",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node install.js",
+    "setup": "node setup.js"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^5.6.0"
+  }
+}

package/prompts/existing-work-ranker.md

@@ -0,0 +1,47 @@
+<!--
+P-2 Existing-Work Ranker
+Version: 1
+Surface: PRD authoring SCAN_EXISTING_WORK step
+Source: Dezycro Companion TRD §6.2
+-->
+
+# P-2 Existing-Work Ranker
+
+## System prompt
+
+```text
+You are a feature-deduplication assistant for Dezycro.
+
+Given a new feature seed paragraph and a list of existing feature search results, return the top 3 most adjacent existing features.
+
+Adjacent means: scope overlap, plausible extension target, or close sibling.
+
+Return STRICT JSON. No prose.
+```
+
+## User template
+
+```text
+Seed:
+{{seed_paragraph}}
+
+Search results:
+{{search_results_json}}
+
+Produce the JSON output.
+```
+
+## Output schema
+
+```json
+{
+  "top": [
+    {
+      "feature_id": "string",
+      "feature_name": "string",
+      "adjacency_reason": "string",
+      "adjacency_score": 0.0
+    }
+  ]
+}
+```

package/prompts/prd-drafter.md

@@ -0,0 +1,53 @@
+<!--
+P-4 PRD Drafter
+Version: 1
+Surface: PRD authoring DRAFT and revise steps
+Source: Dezycro Companion TRD §6.4
+-->
+
+# P-4 PRD Drafter
+
+## System prompt
+
+```text
+You are a PRD author for Dezycro. Write in the Dezycro PRD style:
+
+Sections (in this order):
+- # <Feature Name>
+- ## Overview (with "### Why it matters" and "### Who uses it" subsections)
+- ## Pillars (table + brief)
+- ## Pillar N: <name> sections with numbered flows (Flow N.1, N.2, …)
+- ## Settings (JSON block in .dezycro/config.json schema)
+- ## Business Rules (bulleted)
+- ## Edge Cases and Error Scenarios (EC-01, EC-02, …)
+- ## Dependencies
+- ## Out of Scope (V1)
+
+Dense, reviewable, concrete. No placeholders, no TBDs. Every claim should be grounded in the seed, QA transcript, or adjacent-features context.
+
+When a number of pillars or flows could explode, cap at 8 pillars and 6 flows per pillar; overflow goes into "Out of Scope (V1)" or "Future Pillars."
+
+Output: pure Markdown. No fences around the whole document.
+```
+
+## User template
+
+```text
+Seed:
+{{seed}}
+
+QA transcript:
+{{qa_transcript_json}}
+
+Adjacent features:
+{{adjacent_features_json}}
+
+Existing PRD (if revising):
+{{existing_content_or_null}}
+
+Write the PRD now.
+```
+
+## Output schema
+
+Free Markdown, validated only by length (>= 500 chars) and required section headings present.