@s_s/harmonia 1.0.0 → 1.1.0

package/build/core/types.d.ts

@@ -11,6 +11,17 @@ export interface PhaseDefinition {
     description: string;
 }
 export type DocScale = 'full' | 'lite' | 'skip' | 'optional';
+/** Step definition within a doc (for sequential mode) */
+export interface DocStepDefinition {
+    /** Step ID, e.g. "requirements", "draft", "final" */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Output format for this step's artifact */
+    format: 'json' | 'md';
+    /** Description shown to agent */
+    description: string;
+}
 export interface DocDefinition {
     name: string;
     scale: Record<ProjectScale, DocScale>;
@@ -20,6 +31,8 @@ export interface DocDefinition {
     review?: boolean;
     /** External output — not managed by write_doc (e.g. code written directly to project dir) */
     external?: boolean;
+    /** Sequential steps — when defined and scale >= medium, write_doc requires step parameter */
+    steps?: DocStepDefinition[];
 }
 export interface ScaleDimension {
     small: string | number | boolean;
@@ -29,6 +42,8 @@ export interface ScaleDimension {
 export interface WorkflowDefinition {
     name: string;
     description: string;
+    version?: string;
+    author?: string;
     phases: PhaseDefinition[];
     docs: Record<string, DocDefinition>;
     scale_criteria: {
@@ -36,6 +51,47 @@ export interface WorkflowDefinition {
         dimensions: Record<string, ScaleDimension>;
     };
 }
+/**
+ * A required section (heading) in a markdown document.
+ * Validation checks that the document contains a heading matching the primary
+ * pattern or one of the aliases.
+ */
+export interface DocSchemaSection {
+    /** Primary heading text, e.g. "## 项目概述" */
+    heading: string;
+    /** Per-scale requirement: true = required, false = optional */
+    required: Record<ProjectScale, boolean>;
+    /** Alternative heading texts that satisfy this requirement */
+    aliases?: string[];
+}
+/**
+ * Schema definition for a document type.
+ * Used by write_doc to validate content structure before writing.
+ */
+export interface DocSchema {
+    /** Required sections for markdown documents */
+    sections?: DocSchemaSection[];
+    /** Required HTML tags for html-format documents (e.g. ["html", "body", "nav"]) */
+    htmlTags?: string[];
+    /** Required top-level JSON fields (for JSON step artifacts) */
+    jsonFields?: DocSchemaJsonField[];
+    /** Minimum content length in characters (optional) */
+    minLength?: number;
+}
+/**
+ * A required top-level field in a JSON document.
+ * Used for validating structured step artifacts.
+ */
+export interface DocSchemaJsonField {
+    /** Field name (top-level key in JSON) */
+    field: string;
+    /** Per-scale requirement: true = required, false = optional */
+    required: Record<ProjectScale, boolean>;
+    /** Expected type: "string", "array", "object", "number", "boolean" */
+    type?: string;
+    /** If type is "array", minimum number of items */
+    minItems?: number;
+}
 export interface RoleCapability {
     /** Unique ID for this capability */
     id: string;
@@ -76,8 +132,8 @@ export interface ProjectState {
     projectDir: string;
     /** Workflow name, e.g. "dev" */
     workflow: string;
-    /** Project scale determined by PM */
-    scale: ProjectScale;
+    /** Project scale determined by PM (null until set via project_set_scale) */
+    scale: ProjectScale | null;
     /** Current phase id */
     currentPhase: string;
     /** State of each phase */
@@ -150,8 +206,9 @@ export interface CapabilityOverride {
     /** Additional notes for prompt generation (rarely needed) */
     notes?: string;
 }
-/** Agent type for spawning team member agents */
-export type AgentType = 'opencode' | 'openclaw' | 'claude-code' | 'codex';
+/** Agent type for spawning team member agents (re-exported from @s_s/agent-kit) */
+import type { AgentType } from '@s_s/agent-kit';
+export type { AgentType };
 /** Per-role override configuration */
 export interface RoleOverride {
     /** Agent type to use for this role */
@@ -179,3 +236,23 @@ export interface OverrideConfig {
     /** Role overrides (agent, model, capabilities) */
     roles?: Record<string, RoleOverride>;
 }
+/** Step completion record */
+export interface DocStepRecord {
+    /** Step ID */
+    stepId: string;
+    /** When this step was completed */
+    completedAt: string;
+    /** File path of the step artifact (relative to project data dir) */
+    artifactPath: string;
+}
+/** Per-doc step tracking state */
+export interface DocStepState {
+    /** Doc ID */
+    docId: string;
+    /** Completed steps (in order) */
+    completedSteps: DocStepRecord[];
+    /** Whether the final doc has been written (last step completed + merged) */
+    finalized: boolean;
+    /** Finalized at timestamp */
+    finalizedAt?: string;
+}

package/build/core/workflow.d.ts

@@ -1,13 +1,33 @@
 /**
- * Workflow loader — reads workflow definitions and role prompts from the
- * workflows/ directory bundled with Harmonia.
+ * Workflow loader — two-layer resolution for workflow definitions.
+ *
+ * Lookup priority:
+ *   1. <data_dir>/.workflows/<name>/   (user custom — can override built-in)
+ *   2. <package>/workflows/<name>/      (built-in fallback)
  */
 import type { LoadedWorkflow } from './types.js';
+export declare class WorkflowNotFoundError extends Error {
+    constructor(name: string, searched: string[]);
+}
 /**
- * Load a single workflow by name from the given workflows root directory.
+ * Resolve the actual directory for a workflow name.
+ * Custom dir takes priority over built-in dir.
+ * Returns the resolved directory path.
  */
-export declare function loadWorkflow(workflowsDir: string, name: string): Promise<LoadedWorkflow>;
+export declare function resolveWorkflowDir(builtinDir: string, customDir: string, name: string): Promise<string>;
 /**
- * List all available workflow names.
+ * Load a single workflow by name using two-layer resolution.
+ *
+ * @param builtinDir - Package built-in workflows directory
+ * @param customDir  - User custom workflows directory (<data_dir>/.workflows)
+ * @param name       - Workflow name (directory name)
  */
-export declare function listWorkflows(workflowsDir: string): Promise<string[]>;
+export declare function loadWorkflow(builtinDir: string, customDir: string, name: string): Promise<LoadedWorkflow>;
+/**
+ * List all available workflow names, merging custom and built-in.
+ * Custom workflows override built-in ones with the same name.
+ *
+ * @param builtinDir - Package built-in workflows directory
+ * @param customDir  - User custom workflows directory (<data_dir>/.workflows)
+ */
+export declare function listWorkflows(builtinDir: string, customDir: string): Promise<string[]>;

package/build/core/workflow.js

@@ -1,10 +1,50 @@
 /**
- * Workflow loader — reads workflow definitions and role prompts from the
- * workflows/ directory bundled with Harmonia.
+ * Workflow loader — two-layer resolution for workflow definitions.
+ *
+ * Lookup priority:
+ *   1. <data_dir>/.workflows/<name>/   (user custom — can override built-in)
+ *   2. <package>/workflows/<name>/      (built-in fallback)
  */
-import { readFile, readdir } from 'node:fs/promises';
+import { readFile, readdir, access } from 'node:fs/promises';
 import { join, parse } from 'node:path';
 import YAML from 'yaml';
+// ─── Errors ───
+export class WorkflowNotFoundError extends Error {
+    constructor(name, searched) {
+        const dirs = searched.map((d) => `  - ${d}`).join('\n');
+        super(`工作流 "${name}" 不存在。已搜索:\n${dirs}`);
+        this.name = 'WorkflowNotFoundError';
+    }
+}
+// ─── Internal helpers ───
+/**
+ * Check if a file exists (async, no throw).
+ */
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the actual directory for a workflow name.
+ * Custom dir takes priority over built-in dir.
+ * Returns the resolved directory path.
+ */
+export async function resolveWorkflowDir(builtinDir, customDir, name) {
+    const customPath = join(customDir, name, 'workflow.json');
+    if (await fileExists(customPath)) {
+        return join(customDir, name);
+    }
+    const builtinPath = join(builtinDir, name, 'workflow.json');
+    if (await fileExists(builtinPath)) {
+        return join(builtinDir, name);
+    }
+    throw new WorkflowNotFoundError(name, [join(customDir, name), join(builtinDir, name)]);
+}
 /**
  * Parse a role markdown file.
  * Format: YAML frontmatter (---\n...\n---) followed by markdown prompt.
@@ -32,17 +72,28 @@ function parseRoleFile(id, content) {
     };
     return { id, frontmatter, prompt };
 }
+// ─── Public API ───
 /**
- * Load a single workflow by name from the given workflows root directory.
+ * Load a single workflow by name using two-layer resolution.
+ *
+ * @param builtinDir - Package built-in workflows directory
+ * @param customDir  - User custom workflows directory (<data_dir>/.workflows)
+ * @param name       - Workflow name (directory name)
  */
-export async function loadWorkflow(workflowsDir, name) {
-    const workflowDir = join(workflowsDir, name);
+export async function loadWorkflow(builtinDir, customDir, name) {
+    const workflowDir = await resolveWorkflowDir(builtinDir, customDir, name);
     // Load workflow.json
     const workflowJson = await readFile(join(workflowDir, 'workflow.json'), 'utf-8');
     const definition = JSON.parse(workflowJson);
     // Load roles
     const rolesDir = join(workflowDir, 'roles');
-    const roleFiles = await readdir(rolesDir);
+    let roleFiles = [];
+    try {
+        roleFiles = await readdir(rolesDir);
+    }
+    catch {
+        // roles/ directory is optional for custom workflows
+    }
     const roles = {};
     for (const file of roleFiles) {
         if (!file.endsWith('.md'))
@@ -54,10 +105,36 @@ export async function loadWorkflow(workflowsDir, name) {
     return { definition, roles };
 }
 /**
- * List all available workflow names.
+ * List all available workflow names, merging custom and built-in.
+ * Custom workflows override built-in ones with the same name.
+ *
+ * @param builtinDir - Package built-in workflows directory
+ * @param customDir  - User custom workflows directory (<data_dir>/.workflows)
  */
-export async function listWorkflows(workflowsDir) {
-    const entries = await readdir(workflowsDir, { withFileTypes: true });
-    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+export async function listWorkflows(builtinDir, customDir) {
+    const names = new Set();
+    // Built-in workflows
+    try {
+        const entries = await readdir(builtinDir, { withFileTypes: true });
+        for (const e of entries) {
+            if (e.isDirectory())
+                names.add(e.name);
+        }
+    }
+    catch {
+        // built-in dir missing is unexpected but not fatal
+    }
+    // Custom workflows (can add new or override built-in)
+    try {
+        const entries = await readdir(customDir, { withFileTypes: true });
+        for (const e of entries) {
+            if (e.isDirectory())
+                names.add(e.name);
+        }
+    }
+    catch {
+        // custom dir doesn't exist yet — that's fine
+    }
+    return [...names].sort();
 }
 //# sourceMappingURL=workflow.js.map

package/build/core/workflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflow.js","sourceRoot":"","sources":["../../src/core/workflow.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workflow.js","sourceRoot":"","sources":["../../src/core/workflow.ts"],"names":[],"mappings":"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"}

package/build/hooks/claude-code.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Claude Code / Codex hook definitions.
+ *
+ * Claude Code hooks are shell scripts that receive JSON via stdin.
+ * They can block tool calls via exit code 2 or JSON { decision: "block" }.
+ * UserPromptSubmit stdout is injected as context visible to Claude.
+ *
+ * Hooks:
+ * 1. PreToolUse — boundary guard: block code edits and dev commands
+ * 2. UserPromptSubmit — proactive reminders: dispatch timeout, idle phase, pending reviews
+ *
+ * Project-agnostic: no project name/dir baked in.
+ * - Boundary guard uses tool names + code file extensions only
+ * - Reminders scan all projects under DATA_DIR
+ */
+import type { HookParams } from './content.js';
+/**
+ * Create Claude Code hook definitions using agent-kit's defineHooks.
+ */
+export declare function createClaudeCodeHooks(params: HookParams): import("@s_s/agent-kit").HookSet<"claude-code">;

package/build/hooks/claude-code.js

@@ -0,0 +1,218 @@
+/**
+ * Claude Code / Codex hook definitions.
+ *
+ * Claude Code hooks are shell scripts that receive JSON via stdin.
+ * They can block tool calls via exit code 2 or JSON { decision: "block" }.
+ * UserPromptSubmit stdout is injected as context visible to Claude.
+ *
+ * Hooks:
+ * 1. PreToolUse — boundary guard: block code edits and dev commands
+ * 2. UserPromptSubmit — proactive reminders: dispatch timeout, idle phase, pending reviews
+ *
+ * Project-agnostic: no project name/dir baked in.
+ * - Boundary guard uses tool names + code file extensions only
+ * - Reminders scan all projects under DATA_DIR
+ */
+import { defineHooks } from '@s_s/agent-kit';
+import { BLOCKED_COMMANDS, CODE_EXTENSIONS, DISPATCH_TIMEOUT_MINUTES, PHASE_IDLE_TIMEOUT_MINUTES, REVIEW_PENDING_TIMEOUT_MINUTES, } from './content.js';
+/**
+ * Generate Claude Code PreToolUse hook script.
+ *
+ * Blocks:
+ * - Write/Edit tools targeting code files (by extension)
+ * - Bash tool running dev commands (npm test, node, etc.)
+ *
+ * Allows:
+ * - All Harmonia MCP tools (they go through MCP, not file tools)
+ * - Read-only tools (Read, Glob, Grep, etc.)
+ * - Write/Edit to non-code files (AGENTS.md, docs, etc.)
+ */
+function generatePreToolUseScript(_params) {
+    const codeExtsPattern = CODE_EXTENSIONS.map((e) => `*${e}`).join('|');
+    const blockedCmdsChecks = BLOCKED_COMMANDS.map((cmd) => `  *"${cmd}"*) BLOCKED_CMD="${cmd}" ;;`).join('\n');
+    return `#!/bin/bash
+# Harmonia PM boundary guard — PreToolUse hook
+# Prevents PM from directly modifying code or running dev commands.
+# Generated by Harmonia setup. Do not edit manually.
+
+set -euo pipefail
+
+# Read JSON from stdin
+INPUT=$(cat -)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+TOOL_INPUT=$(echo "$INPUT" | jq -r '.tool_input // empty')
+
+# ── Helper: block with reason ──
+block() {
+  echo "{\\"decision\\":\\"block\\",\\"reason\\":\\"$1\\"}" 
+  exit 0
+}
+
+# ── Guard 1: Write/Edit tools — check file extension ──
+case "$TOOL_NAME" in
+  Write|Edit|MultiEdit|write|edit)
+    # Extract file path from tool input
+    FILE_PATH=$(echo "$TOOL_INPUT" | jq -r '.file_path // .filePath // .path // empty')
+    
+    if [ -z "$FILE_PATH" ]; then
+      exit 0  # No path to check, let it through
+    fi
+
+    # Block writes to code files (by extension)
+    case "$FILE_PATH" in
+      ${codeExtsPattern})
+        block "PM 不应直接修改代码文件。请通过 role_dispatch 将编码任务分配给 developer。文件: $FILE_PATH"
+        ;;
+    esac
+    ;;
+esac
+
+# ── Guard 2: Bash/Terminal — check for dev commands ──
+case "$TOOL_NAME" in
+  Bash|bash|Terminal|terminal)
+    COMMAND=$(echo "$TOOL_INPUT" | jq -r '.command // .cmd // empty')
+    
+    if [ -z "$COMMAND" ]; then
+      exit 0
+    fi
+
+    BLOCKED_CMD=""
+    case "$COMMAND" in
+${blockedCmdsChecks}
+    esac
+
+    if [ -n "$BLOCKED_CMD" ]; then
+      block "PM 不应直接执行开发命令 ($BLOCKED_CMD...)。请通过 role_dispatch 将任务分配给相应角色（developer/tester）。"
+    fi
+    ;;
+esac
+
+# All other tools — allow
+exit 0
+`;
+}
+/**
+ * Generate Claude Code UserPromptSubmit hook script.
+ *
+ * Scans all projects under DATA_DIR for:
+ * - Running dispatches that exceed timeout
+ * - Idle phase warning
+ * - Pending document reviews
+ */
+function generateUserPromptSubmitScript(params) {
+    return `#!/bin/bash
+# Harmonia proactive reminder — UserPromptSubmit hook
+# Reads Harmonia data files and injects status reminders as context.
+# Generated by Harmonia setup. Do not edit manually.
+
+DATA_DIR="${params.dataDir}"
+
+REMINDERS=""
+
+add_reminder() {
+  if [ -n "$REMINDERS" ]; then
+    REMINDERS="$REMINDERS
+$1"
+  else
+    REMINDERS="$1"
+  fi
+}
+
+NOW_EPOCH=$(date +%s)
+
+# ── Scan all projects under DATA_DIR ──
+if [ -d "$DATA_DIR" ]; then
+  for PROJECT_DATA in "$DATA_DIR"/*/; do
+    [ -d "$PROJECT_DATA" ] || continue
+    PROJECT_NAME=$(basename "$PROJECT_DATA")
+
+    # ── Check 1: Running dispatch timeout ──
+    DISPATCHES_FILE="$PROJECT_DATA/dispatches.json"
+    if [ -f "$DISPATCHES_FILE" ]; then
+      RUNNING=$(jq -r '.[] | select(.status == "running" or .status == "dispatched") | "\\(.id)|\\(.role)|\\(.updatedAt)"' "$DISPATCHES_FILE" 2>/dev/null || true)
+      
+      while IFS='|' read -r DID DROLE DUPDATED; do
+        [ -z "$DID" ] && continue
+        UPDATED_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%S" "$(echo "$DUPDATED" | cut -c1-19)" +%s 2>/dev/null || echo "0")
+        if [ "$UPDATED_EPOCH" != "0" ]; then
+          ELAPSED_MIN=$(( (NOW_EPOCH - UPDATED_EPOCH) / 60 ))
+          if [ "$ELAPSED_MIN" -ge ${DISPATCH_TIMEOUT_MINUTES} ]; then
+            add_reminder "- [$PROJECT_NAME] dispatch $DID ($DROLE) 已运行 $ELAPSED_MIN 分钟，建议调用 project_status 检查进度"
+          fi
+        fi
+      done <<< "$RUNNING"
+    fi
+
+    # ── Check 2: Pending document reviews ──
+    REVIEWS_FILE="$PROJECT_DATA/reviews.json"
+    if [ -f "$REVIEWS_FILE" ]; then
+      PENDING=$(jq -r 'to_entries[] | select(.value.status == "pending") | "\\(.key)|\\(.value.submittedAt)"' "$REVIEWS_FILE" 2>/dev/null || true)
+      PENDING_COUNT=0
+      PENDING_DOCS=""
+      
+      while IFS='|' read -r DOC_ID SUBMITTED_AT; do
+        [ -z "$DOC_ID" ] && continue
+        SUBMITTED_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%S" "$(echo "$SUBMITTED_AT" | cut -c1-19)" +%s 2>/dev/null || echo "0")
+        if [ "$SUBMITTED_EPOCH" != "0" ]; then
+          ELAPSED_MIN=$(( (NOW_EPOCH - SUBMITTED_EPOCH) / 60 ))
+          if [ "$ELAPSED_MIN" -ge ${REVIEW_PENDING_TIMEOUT_MINUTES} ]; then
+            PENDING_COUNT=$((PENDING_COUNT + 1))
+            PENDING_DOCS="$PENDING_DOCS $DOC_ID"
+          fi
+        fi
+      done <<< "$PENDING"
+      
+      if [ "$PENDING_COUNT" -gt 0 ]; then
+        add_reminder "- [$PROJECT_NAME] $PENDING_COUNT 份文档待审核超过 ${REVIEW_PENDING_TIMEOUT_MINUTES} 分钟:$PENDING_DOCS — 请尽快处理（doc_approve / reject_doc）"
+      fi
+    fi
+
+    # ── Check 3: Phase idle check ──
+    STATE_FILE="$PROJECT_DATA/state.json"
+    if [ -f "$STATE_FILE" ]; then
+      UPDATED_AT=$(jq -r '.updatedAt // empty' "$STATE_FILE" 2>/dev/null || true)
+      CURRENT_PHASE=$(jq -r '.currentPhase // empty' "$STATE_FILE" 2>/dev/null || true)
+      
+      if [ -n "$UPDATED_AT" ] && [ -n "$CURRENT_PHASE" ]; then
+        STATE_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%S" "$(echo "$UPDATED_AT" | cut -c1-19)" +%s 2>/dev/null || echo "0")
+        if [ "$STATE_EPOCH" != "0" ]; then
+          IDLE_MIN=$(( (NOW_EPOCH - STATE_EPOCH) / 60 ))
+          if [ "$IDLE_MIN" -ge ${PHASE_IDLE_TIMEOUT_MINUTES} ]; then
+            add_reminder "- [$PROJECT_NAME] 当前阶段 ($CURRENT_PHASE) 已空闲 $IDLE_MIN 分钟，建议调用 project_status 检查项目状态"
+          fi
+        fi
+      fi
+    fi
+  done
+fi
+
+# ── Output reminders ──
+if [ -n "$REMINDERS" ]; then
+  echo "<harmonia-reminder>"
+  echo "以下事项需要你的关注："
+  echo ""
+  echo "$REMINDERS"
+  echo ""
+  echo "请根据提醒采取相应行动。"
+  echo "</harmonia-reminder>"
+fi
+
+exit 0
+`;
+}
+/**
+ * Create Claude Code hook definitions using agent-kit's defineHooks.
+ */
+export function createClaudeCodeHooks(params) {
+    return defineHooks('claude-code', [
+        {
+            events: ['PreToolUse'],
+            content: generatePreToolUseScript(params),
+        },
+        {
+            events: ['UserPromptSubmit'],
+            content: generateUserPromptSubmitScript(params),
+        },
+    ]);
+}
+//# sourceMappingURL=claude-code.js.map

package/build/hooks/claude-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-code.js","sourceRoot":"","sources":["../../src/hooks/claude-code.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EACH,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,0BAA0B,EAC1B,8BAA8B,GACjC,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;GAWG;AACH,SAAS,wBAAwB,CAAC,OAAmB;IACjD,MAAM,eAAe,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtE,MAAM,iBAAiB,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,GAAG,oBAAoB,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE5G,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA8BH,eAAe;;;;;;;;;;;;;;;;;;EAkBrB,iBAAiB;;;;;;;;;;;CAWlB,CAAC;AACF,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,8BAA8B,CAAC,MAAkB;IACtD,OAAO;;;;;YAKC,MAAM,CAAC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oCA+BU,wBAAwB;;;;;;;;;;;;;;;;;;;oCAmBxB,8BAA8B;;;;;;;;kEAQA,8BAA8B;;;;;;;;;;;;;;iCAc/D,0BAA0B;;;;;;;;;;;;;;;;;;;;;CAqB1D,CAAC;AACF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAkB;IACpD,OAAO,WAAW,CAAC,aAAa,EAAE;QAC9B;YACI,MAAM,EAAE,CAAC,YAAY,CAAC;YACtB,OAAO,EAAE,wBAAwB,CAAC,MAAM,CAAC;SAC5C;QACD;YACI,MAAM,EAAE,CAAC,kBAAkB,CAAC;YAC5B,OAAO,EAAE,8BAA8B,CAAC,MAAM,CAAC;SAClD;KACJ,CAAC,CAAC;AACP,CAAC"}

package/build/hooks/content.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Hook content generation — shared configuration and rule definitions.
+ *
+ * Hook scripts run on the agent side (shell scripts for Claude Code,
+ * TS plugins for OpenCode, handlers for OpenClaw). They need to know:
+ *   - HARMONIA_DATA_DIR: where to read dispatches.json, state.json, etc.
+ *
+ * Project-specific info (name, dir) is NOT baked in — hooks are project-agnostic.
+ * Boundary guards work on tool names + code file extensions only.
+ * Proactive reminders scan all projects under the data directory.
+ */
+/**
+ * Parameters needed to generate hook content.
+ * Passed at install time and embedded into the generated scripts.
+ */
+export interface HookParams {
+    /** Harmonia data directory (absolute path) */
+    dataDir: string;
+}
+/**
+ * Tool names that PM should not call directly (code modification tools).
+ * These are the standard agent tool names across different platforms.
+ */
+export declare const BLOCKED_TOOLS: readonly ["Write", "Edit", "MultiEdit", "write", "edit", "Bash", "bash", "Terminal", "terminal"];
+/**
+ * Shell commands that indicate development work (PM should not run these).
+ */
+export declare const BLOCKED_COMMANDS: readonly ["npm run", "npm test", "npm start", "npm run build", "npx ", "yarn ", "pnpm ", "bun ", "node ", "deno ", "python ", "cargo ", "go run", "go test", "make ", "gcc ", "g++ ", "javac ", "mvn ", "gradle "];
+/**
+ * File extensions that indicate source code (PM should not modify these).
+ */
+export declare const CODE_EXTENSIONS: readonly [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".rs", ".go", ".java", ".c", ".cpp", ".h", ".hpp", ".cs", ".rb", ".php", ".swift", ".kt", ".vue", ".svelte"];
+/**
+ * Harmonia MCP tool names — these are always allowed since PM uses them
+ * through Harmonia's own tool system.
+ */
+export declare const HARMONIA_TOOLS: readonly ["project_init", "project_set_scale", "project_status", "phase_update", "role_dispatch", "dispatch_report", "doc_write", "doc_read", "doc_list", "doc_approve", "reject_doc", "guard_set", "guard_get", "review_set_rule", "review_list"];
+/** Dispatch running timeout — warn after this many minutes */
+export declare const DISPATCH_TIMEOUT_MINUTES = 30;
+/** Phase idle timeout — warn after this many minutes with no tool calls */
+export declare const PHASE_IDLE_TIMEOUT_MINUTES = 15;
+/** Review pending timeout — warn after this many minutes */
+export declare const REVIEW_PENDING_TIMEOUT_MINUTES = 10;