@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/core/harnesses/claude/hooks/session-end.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# session-end.sh — SessionEnd hook
+#
+# Runs when Claude Code closes a session. Responsibilities:
+#   1. Append END marker to sessions.log
+#   2. Write uncommitted-warning.txt if the working tree is dirty
+#   3. Delete the session-scoped state directory (cleanup)
+#   4. Trim sessions.log to last 500 lines (lock-guarded for parallel safety)
+#
+# Multi-session safe: with_file_lock (lib.sh) prevents concurrent sessions from
+# corrupting the log trim. Session directory deletion is per session_id so
+# sessions don't interfere.
+# Must never exit non-zero or block (SessionEnd is fire-and-forget).
+
+set -euo pipefail
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+require_jq
+
+INPUT=$(cat)
+SESSION_ID=$(json_field "$INPUT" ".session_id")
+CWD=$(json_field "$INPUT" ".cwd")
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# ── 1. Log session end ────────────────────────────────────────────────────────
+
+mkdir -p "$(dirname "$SESSIONS_LOG")"
+echo "$TIMESTAMP END ${SESSION_ID:-unknown} ${CWD:-unknown}" >> "$SESSIONS_LOG"
+
+# ── 2. Uncommitted-changes warning ────────────────────────────────────────────
+
+# A worker session never writes the project's warning; it is left for the main session.
+if [[ "$(doflow_session_role || echo main)" != "worker" ]] && [[ -n "$CWD" ]] && is_git_worktree "$CWD"; then
+  if has_uncommitted_changes "$CWD"; then
+    BRANCH=$(git_branch_of "$CWD" || echo "unknown")
+    PROJECT_DIR=$(ensure_project_dir "$CWD")
+    echo "Session ${SESSION_ID:-unknown} ended with uncommitted changes on branch ${BRANCH}" \
+      > "$PROJECT_DIR/uncommitted-warning.txt"
+  fi
+fi
+
+# ── 2b. Update meta.json last_active ─────────────────────────────────────────
+
+if [[ -n "$CWD" ]]; then
+  PROJECT_DIR=$(ensure_project_dir "$CWD")
+  if [[ -f "$PROJECT_DIR/meta.json" ]]; then
+    META_TMP=$(mktemp "$PROJECT_DIR/.meta.XXXXXX")
+    jq --arg ts "$TIMESTAMP" '.last_active = $ts' "$PROJECT_DIR/meta.json" \
+      > "$META_TMP" && mv "$META_TMP" "$PROJECT_DIR/meta.json" \
+      || rm -f "$META_TMP" 2>/dev/null || true
+  fi
+fi
+
+# ── 3. Delete session directory ───────────────────────────────────────────────
+
+if [[ -n "$SESSION_ID" ]]; then
+  SESSION_PATH="$SESSION_DIR/$SESSION_ID"
+  rm -rf "$SESSION_PATH" 2>/dev/null || true
+fi
+
+(
+  SHARED_POLICY_LIB="$(dirname "$0")/../../.doflow/shared/hooks/policies/lib.sh"
+  if [[ ! -f "$SHARED_POLICY_LIB" ]]; then
+    SHARED_POLICY_LIB="$(dirname "$0")/../../shared/hooks/policies/lib.sh"
+  fi
+  if [[ -f "$SHARED_POLICY_LIB" ]]; then
+    source "$SHARED_POLICY_LIB"
+    storage_upkeep_async "$CWD"
+  fi
+) >/dev/null 2>&1 || true
+
+# ── 4. Trim sessions.log (lock-guarded) ───────────────────────────────────────
+
+LOCK_FILE="${SESSIONS_LOG}.lock"
+if with_file_lock "$LOCK_FILE" 5; then
+  trap 'release_file_lock "$LOCK_FILE"' EXIT
+  if [[ -f "$SESSIONS_LOG" ]]; then
+    TMP=$(mktemp "${SESSIONS_LOG}.XXXXXX")
+    if tail -n 500 "$SESSIONS_LOG" > "$TMP"; then
+      mv "$TMP" "$SESSIONS_LOG" || rm -f "$TMP"
+    else
+      rm -f "$TMP"
+    fi
+  fi
+  release_file_lock "$LOCK_FILE"
+fi
+
+exit 0

package/core/harnesses/claude/hooks/session-start.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Claude adapter: reuse the shared session initializer with Claude attribution.
+set -euo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-claude}"
+exec bash "$(dirname "$0")/../../.doflow/shared/hooks/policies/session-context.sh"

package/core/harnesses/claude/hooks/skill-config-audit.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# skill-config-audit.sh — ConfigChange(skills) hook (pure observability, no deny path)
+#
+# Logs skill-file mutations regardless of which tool made them (a subagent's Bash heredoc-to-file
+# write, an MCP filesystem tool, a plugin) — not just the Edit/Write tools pre-implement-gate.sh
+# already watches for the doflow chain's own narrower purpose. Appends
+# {timestamp, session_id, event} to a session-scoped log, same convention as subagent-audit.sh.
+#
+# Per agent-docs/research/hook-governance-agent-tool-mcp-skill.md §3.4: skill files get
+# legitimately edited during normal development (this project's own doflow-framework tooling
+# among them), so a naive hard-block on skill-file change would fight that — `decision: "block"`
+# is deliberately NOT used here.
+# This ships pure-logging only; a stricter follow-on (only once the log shows what "normal" skill
+# churn looks like in practice) is a separate, later decision.
+#
+# Multi-session safe: writes only to sessions/{session_id}/skill-config-audit.log.
+# Must never exit non-zero or block a config change.
+
+set -euo pipefail
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+require_jq
+
+INPUT=$(cat)
+SESSION_ID=$(json_field "$INPUT" ".session_id")
+
+# Guard: if we can't determine the session, nothing to do
+[[ -z "$SESSION_ID" ]] && exit 0
+
+TIMESTAMP=$(date -u +%FT%TZ)
+SESSION_PATH=$(ensure_session_dir "$SESSION_ID")
+
+jq -nc \
+  --arg ts "$TIMESTAMP" \
+  --arg session "$SESSION_ID" \
+  '{timestamp: $ts, session_id: $session, event: "ConfigChange", source: "skills"}' \
+  >> "$SESSION_PATH/skill-config-audit.log" 2>/dev/null || true
+
+exit 0

package/core/harnesses/claude/hooks/stop-check.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Claude adapter: reuse the shared stop-completion check with Claude attribution.
+set -euo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-claude}"
+exec bash "$(dirname "$0")/../../.doflow/shared/hooks/policies/stop-check.sh"

package/core/harnesses/claude/hooks/subagent-audit.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Claude front door: reuse the canonical subagent-audit policy with Claude attribution.
+# No JSON-shape translation needed — claude/codex's copies were byte-identical
+# (022-hooks-remaining-duplication).
+set -euo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-claude}"
+exec bash "$(dirname "$0")/../../.doflow/shared/hooks/policies/subagent-audit.sh"

package/core/harnesses/claude/hooks/user-prompt-submit.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Claude front door: reuse the canonical context policy with Claude's output envelope.
+set -euo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-claude}"
+exec bash "$(dirname "$0")/../../.doflow/shared/hooks/policies/user-prompt-submit.sh"

package/core/harnesses/claude/settings/keybindings.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
+  "$docs": "https://code.claude.com/docs/en/keybindings",
+  "bindings": [
+    {
+      "context": "Global",
+      "bindings": {
+        "ctrl+shift+t": "app:toggleTodos",
+        "ctrl+shift+o": "app:toggleTranscript"
+      }
+    },
+    {
+      "context": "Chat",
+      "bindings": {
+        "ctrl+e": "chat:externalEditor",
+        "ctrl+g": null
+      }
+    }
+  ]
+}

package/core/harnesses/claude/settings/settings.json

@@ -0,0 +1,201 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "env": {
+    "MCP_TIMEOUT": "120000",
+    "ENABLE_TOOL_SEARCH": "true",
+    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "75"
+  },
+  "outputStyle": "Explanatory",
+  "enableAllProjectMcpServers": true,
+  "plansDirectory": "./agent-docs",
+  "permissions": {
+    "allow": [
+      "Bash(git *:*)",
+      "Bash(./gradlew *:*)",
+      "Bash(npm *:*)",
+      "Bash(python *:*)",
+      "Bash(pytest *:*)",
+      "Bash(mvn *:*)"
+    ],
+    "deny": [
+      "Bash(git push --force*:*)",
+      "Bash(git reset --hard*:*)",
+      "Bash(git clean -fd*:*)"
+    ]
+  },
+  "alwaysThinkingEnabled": true,
+  "cleanupPeriodDays": 60,
+  "autoUpdatesChannel": "stable",
+  "availableModels": [
+    "opus",
+    "sonnet",
+    "haiku"
+  ],
+  "model": "sonnet",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/user-prompt-submit.sh"
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/subagent-audit.sh"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/subagent-audit.sh"
+          }
+        ]
+      }
+    ],
+    "ConfigChange": [
+      {
+        "matcher": "skills",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/skill-config-audit.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/pre-bash-guard.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/mcp-tool-guard.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/pre-implement-gate.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/post-edit-lint.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/post-edit-lint.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/stop-check.sh"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/pre-compact.sh"
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/post-compact.sh"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/session-end.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/post-tool-failure.sh"
+          }
+        ]
+      }
+    ],
+    "PermissionDenied": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/permission-audit.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/core/harnesses/claude/statusline/doflow-statusline.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# doflow-statusline — Claude Code status line fed by DoFlow's neutral state.
+#
+# Claude Code pipes one session-state JSON document to stdin; whatever this script prints becomes
+# the persistent status row. Everything here is best-effort: any failure prints the static prefix
+# and exits 0, because a broken status line must never break the session.
+#
+# Rendered segments (space-separated, dash-joined):
+#   branch   — current git branch, when stdin carries a git-capable cwd
+#   task     — active task id from .doflow/state/orchestration/ (project scope)
+#   readiness— last recorded readiness verdict for that task
+
+set -euo pipefail
+
+input=$(cat)
+
+cwd=$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null || true)
+branch=""
+task=""
+
+if [[ -n "$cwd" && -d "$cwd/.git" ]] || git -C "${cwd:-.}" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  branch=$(git -C "${cwd:-.}" branch --show-current 2>/dev/null || true)
+fi
+
+state_root=".doflow/state"
+if [[ -n "$cwd" && -d "$cwd/$state_root" ]]; then
+  state_root="$cwd/$state_root"
+elif [[ ! -d "$state_root" ]]; then
+  state_root=""
+fi
+
+if [[ -n "$state_root" ]]; then
+  cursor=$(ls -t "$state_root"/orchestration/*.json 2>/dev/null | head -1 || true)
+  if [[ -n "$cursor" ]]; then
+    task=$(jq -r '.taskId // empty' "$cursor" 2>/dev/null || true)
+  fi
+fi
+
+segments=()
+[[ -n "$branch" ]] && segments+=("$branch")
+[[ -n "$task" ]] && segments+=("task:$task")
+
+if [[ ${#segments[@]} -eq 0 ]]; then
+  echo "doflow"
+else
+  printf 'doflow '
+  printf '%s ' "${segments[@]:-}"
+  printf '\n'
+fi

package/core/harnesses/codex/agents/core-implementer.toml

@@ -0,0 +1,7 @@
+name = "core-implementer"
+description = "Specialist code engineer for full-stack implementation, clean refactoring, and performance optimization."
+developer_instructions = """
+Implement features and refactor code strictly according to approved designs and task checklists.
+Optimize algorithms, reduce complexity, and maintain polyglot code quality across the codebase.
+Ensure changes pass all existing tests and conform to language-specific standards.
+"""

package/core/harnesses/codex/agents/quality-guardian.toml

@@ -0,0 +1,8 @@
+name = "quality-guardian"
+description = "Specialist quality and security engineer for automated testing, security audits, and root cause analysis."
+sandbox_mode = "read-only"
+developer_instructions = """
+Author and run comprehensive test suites, audit code for security vulnerabilities, and diagnose root causes.
+Verify adherence to SOLID principles, check error handling boundaries, and analyze reproduction traces.
+Stay in audit mode: do not modify business logic code directly without an approved fix plan.
+"""

package/core/harnesses/codex/agents/research-writer.toml

@@ -0,0 +1,8 @@
+name = "research-writer"
+description = "Specialist research and technical writing agent for documentation, architecture indices, and web research."
+sandbox_mode = "read-only"
+developer_instructions = """
+Conduct deep web research with cited sources and write comprehensive technical documentation.
+Create project architecture indices and implementation flow summaries capturing architectural trade-offs.
+Stay in documentation mode: do not modify workspace source code.
+"""

package/core/harnesses/codex/agents/spec-analyst.toml

@@ -0,0 +1,8 @@
+name = "spec-analyst"
+description = "Specialist agent for requirements discovery, user story breakdown, and estimation."
+sandbox_mode = "read-only"
+developer_instructions = """
+Elicit requirements through Socratic dialogue focusing on user value and business goals.
+Decompose initiatives into user stories with testable acceptance criteria and estimate effort.
+Stay in planning mode: do not implement code or modify workspace files.
+"""

package/core/harnesses/codex/agents/system-architect.toml

@@ -0,0 +1,9 @@
+name = "system-architect"
+description = "Specialist architect agent for system design, API contracts, and infrastructure."
+sandbox_mode = "read-only"
+developer_instructions = """
+Design scalable systems with explicit component boundaries, interfaces, dependencies, and trade-offs.
+Evaluate architecture decisions for maintainability, resilience, operational impact, and future change.
+Document clear recommendations with alternatives and validation criteria.
+Stay in planning mode: do not implement code or modify workspace files.
+"""

package/core/harnesses/codex/config/config.toml

@@ -0,0 +1,10 @@
+# DoFlow Codex configuration source.
+#
+# This deliberately contains only the lifecycle-hook feature flag. The installer
+# owns just this key and must preserve every unrelated Codex setting, provider,
+# MCP server, and custom-agent declaration when it reconciles this file.
+# Hooks themselves live exclusively in hooks.json beside this config; do not add
+# inline [hooks] tables here because Codex would load both representations.
+
+[features]
+hooks = true

package/core/harnesses/codex/hooks/hooks.json

@@ -0,0 +1,122 @@
+{
+  "description": "DoFlow lifecycle hooks for Codex. Review and trust these hooks in Codex before use.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.codex/hooks/session-start.sh\" ] && printf '%s/.codex/hooks/session-start.sh' \"$root\" || printf '%s/hooks/session-start.sh' \"${CODEX_HOME:-$HOME/.codex}\")\"",
+            "statusMessage": "Preparing DoFlow session context"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.codex/hooks/user-prompt-submit.sh\" ] && printf '%s/.codex/hooks/user-prompt-submit.sh' \"$root\" || printf '%s/hooks/user-prompt-submit.sh' \"${CODEX_HOME:-$HOME/.codex}\")\""
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.codex/hooks/subagent-audit.sh\" ] && printf '%s/.codex/hooks/subagent-audit.sh' \"$root\" || printf '%s/hooks/subagent-audit.sh' \"${CODEX_HOME:-$HOME/.codex}\")\""
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.codex/hooks/subagent-audit.sh\" ] && printf '%s/.codex/hooks/subagent-audit.sh' \"$root\" || printf '%s/hooks/subagent-audit.sh' \"${CODEX_HOME:-$HOME/.codex}\")\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "^Bash$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.codex/hooks/pre-bash-guard.sh\" ] && printf '%s/.codex/hooks/pre-bash-guard.sh' \"$root\" || printf '%s/hooks/pre-bash-guard.sh' \"${CODEX_HOME:-$HOME/.codex}\")\"",
+            "statusMessage": "Checking command safety"
+          }
+        ]
+      },
+      {
+        "matcher": "^mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.codex/hooks/mcp-tool-guard.sh\" ] && printf '%s/.codex/hooks/mcp-tool-guard.sh' \"$root\" || printf '%s/hooks/mcp-tool-guard.sh' \"${CODEX_HOME:-$HOME/.codex}\")\"",
+            "statusMessage": "Checking MCP policy"
+          }
+        ]
+      },
+      {
+        "matcher": "^(apply_patch|Edit|Write)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.codex/hooks/pre-implement-gate.sh\" ] && printf '%s/.codex/hooks/pre-implement-gate.sh' \"$root\" || printf '%s/hooks/pre-implement-gate.sh' \"${CODEX_HOME:-$HOME/.codex}\")\"",
+            "statusMessage": "Checking DoFlow prerequisites"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^(apply_patch|Edit|Write)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.codex/hooks/post-edit-lint.sh\" ] && printf '%s/.codex/hooks/post-edit-lint.sh' \"$root\" || printf '%s/hooks/post-edit-lint.sh' \"${CODEX_HOME:-$HOME/.codex}\")\""
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.codex/hooks/pre-compact.sh\" ] && printf '%s/.codex/hooks/pre-compact.sh' \"$root\" || printf '%s/hooks/pre-compact.sh' \"${CODEX_HOME:-$HOME/.codex}\")\"",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.codex/hooks/stop-check.sh\" ] && printf '%s/.codex/hooks/stop-check.sh' \"$root\" || printf '%s/hooks/stop-check.sh' \"${CODEX_HOME:-$HOME/.codex}\")\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$(root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -f \"$root/.codex/hooks/session-end.sh\" ] && printf '%s/.codex/hooks/session-end.sh' \"$root\" || printf '%s/hooks/session-end.sh' \"${CODEX_HOME:-$HOME/.codex}\")\"",
+            "timeout": 3
+          }
+        ]
+      }
+    ]
+  }
+}