@mamdouh-aboammar/agentic-workflow 1.2.0

package/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: agentic-workflow
+description: >
+  Pluripotent stem-cell framework and universal agentic toolchain for autonomous
+  workflows. Use when designing, building, orchestrating, validating, or optimizing
+  complex multi-step AI agent workflows across Research, Planning, and Implementation —
+  even if the user says "build an autonomous pipeline", "design agent workflow",
+  "execute in autopilot", "run ulw mode", or "setup quality gates". Do NOT use for
+  simple single-file one-off edits without workflow structure.
+---
+
+# AgenticWorkflow: Universal Agentic Skill & Execution Toolchain
+
+A pluripotent stem-cell framework and multi-agent execution engine that turns complex tasks into deterministic, self-verifying autonomous workflows.
+
+## Execution Invariant
+
+$$\text{Intent} \xrightarrow{\text{Research}} \text{Plan (SOT state.yaml)} \xrightarrow{\text{Implementation}} \text{4-Layer Quality Gates} \xrightarrow{\text{pACS Delta}} \text{Verified Deliverable}$$
+
+---
+
+## ⚡ Dynamic Mode Router
+
+Detect the desired mode from context or explicit flags:
+
+| Mode | Trigger Phrases | Core Execution Flow |
+|---|---|---|
+| **1. DESIGN** | "design workflow", "new pipeline", "workflow.md" | Research → Planning → Implementation 3-stage blueprint generation |
+| **2. EXECUTE** | "run workflow", "execute pipeline", "start step" | SOT state-machine driver with step-by-step deliverable generation |
+| **3. AUTOPILOT**| "autopilot", "fully automated", "hands-off" | Auto-approve `(human)` checkpoints with decision logs; enforce safety hooks |
+| **4. ULW** | "ulw", "ultrawork", "maximum rigor" | 3 Intensifiers: Sisyphus Persistence, Mandatory Decomposition, Retry Escalation |
+| **5. VERIFY** | "verify step", "quality gates", "run pacs" | L0 Anti-Skip → L1 Verification → L1.5 pACS → L2 Adversarial Review |
+| **6. OPTIMIZE**| "optimize workflow", "reduce cycle time", "streamline" | Lean bottleneck analysis, automation scoring, cycle time compression |
+
+---
+
+## 3 Absolute Criteria (Constitutional Canon)
+
+Every workflow, tool, and subagent created or governed by this skill strictly inherits the 3 Absolute Criteria:
+
+1. **Absolute Criterion 1: Quality of the Final Deliverable**
+   > Speed, token cost, workload, and length limits are completely ignored. The sole criterion for every decision is the **quality of the final deliverable**.
+2. **Absolute Criterion 2: Single-File SOT + Hierarchical Memory**
+   > All shared state is concentrated in a single file (`state.yaml`). SOT write permission belongs exclusively to the Orchestrator / Team Lead. Parallel agents never mutate shared files simultaneously.
+3. **Absolute Criterion 3: Code Change Protocol (CCP)**
+   > Before writing, modifying, adding, or deleting code, internally perform: Step 1 (Understand Intent) → Step 2 (Ripple Effect Analysis) → Step 3 (Change Plan). Governed by Coding Anchor Points (CAP-1~4).
+
+---
+
+## 4-Layer Quality Assurance Stack
+
+```mermaid
+flowchart TD
+    StepStart["Step Execution"] --> L0["L0: Anti-Skip Physical Guard (File exists & >= 100 bytes)"]
+    L0 -->|PASS| L1["L1: Verification Gate (100% functional goal achievement)"]
+    L0 -->|FAIL| Diag["Abductive Diagnosis"]
+    L1 -->|PASS| L15["L1.5: pACS Self-Rating (F/C/L Pre-mortem scoring)"]
+    L1 -->|FAIL| Diag
+    L15 -->|RED: <50| Diag
+    L15 -->|GREEN / YELLOW| L2["L2: Adversarial Review (@reviewer + @fact-checker)"]
+    L2 -->|PASS| SOT["Advance SOT (current_step + 1)"]
+    L2 -->|FAIL| Diag
+    Diag --> Retry["Retry with Alternative Hypothesis (Max 3)"]
+```
+
+1. **L0 Anti-Skip Guard**: Deterministically verifies deliverable exists on disk and is non-empty (`MIN_OUTPUT_SIZE >= 100 bytes`).
+2. **L1 Verification Gate**: Semantic verification that all acceptance criteria are 100% achieved.
+3. **L1.5 pACS (Predicted Agent Confidence Score)**: Pre-mortem evaluation across Faithfulness, Completeness, Logic. $pACS = \min(F, C, L)$.
+   - `GREEN (>= 70)`: Auto-advance.
+   - `YELLOW (50 - 69)`: Flag weak dimension in Decision Log and proceed.
+   - `RED (< 50)`: Halt and trigger rework.
+4. **L2 Adversarial Review**: Independent Generator-Critic evaluation by `@reviewer` and `@fact-checker`.
+
+---
+
+## Autonomous Self-Fueling Engine & Circuit Breaker
+
+The system operates as an end-to-end autonomous engine with built-in energy management:
+1. **Self-Fueling & Energy Loop**: Dynamic token and context headroom monitoring with automatic RLM state compaction and refueling checkpoints before context exhaustion.
+2. **Fable Circuit Breaker**: State transitions `CLOSED` → `OPEN` → `HALF_OPEN`. Automatically halts speculative thrashing when consecutive failure streak $\ge 2$, isolates root causes via Abductive Diagnosis (`diagnose_context.py`), and executes structured recovery.
+3. **Clean Code Guard**: Automated AST guard pass checking the 24 Clean Code imperatives (small functions, intent-revealing names, maximum 4 parameters, no swallowed exceptions, no fake success mocks).
+4. **AI Engineering Evaluation**: Integrated four-fifths disparate impact testing ($\ge 0.80$), PSI distribution drift monitoring, and adversarial prompt-injection sanitization.
+5. **OmniSkill Dynamic Intent Routing**: Decomposes complex natural language intent into an optimal multi-step DAG across Research, Planning, Implementation, and Verification.
+
+---
+
+## CLI & Toolchain Integration
+
+```bash
+# Launch autonomous end-to-end autopilot workflow with self-fueling & energy management
+agentic-workflow autopilot --title "Production Pipeline" --goal "Autonomous Delivery"
+
+# Run Clean Code Guard audit pass (SOLID, 24 Imperatives, AI failure modes)
+agentic-workflow guard [directory]
+
+# Execute AI Engineer fairness, drift, and prompt-injection evaluation gates
+agentic-workflow eval
+
+# Query multi-agent observable trace logs and spans
+agentic-workflow traces
+
+# Run OmniSkill dynamic intent routing and multi-host validation
+agentic-workflow omni-skill route "build an autonomous pipeline"
+agentic-workflow omni-skill validate
+
+# Check live workflow dashboard and observability metrics
+agentic-workflow status
+
+# Run full automated test suite (safety, guard, MAS, evaluator)
+agentic-workflow test
+```
+
+---
+
+## Universal Multi-Agent & Multi-Host Distribution
+
+Install and use AgenticWorkflow instantly across any platform or AI harness:
+
+```bash
+# Skills.sh / Vercel AI (Universal Agent Discovery)
+npx skills add imMamdouhaboammar/agentic-workflow
+
+# Zero-Install CLI (Bun & Node/npx)
+bunx agentic-workflow --help
+npx agentic-workflow --help
+
+# Python Environment (pip / PyPI)
+pip install agentic-workflow
+
+# Universal Multi-Agent Installer (Claude, Gemini, Cursor, Codex, OpenCode)
+curl -fsSL https://raw.githubusercontent.com/imMamdouhaboammar/agentic-workflow/main/install.sh | bash
+```

package/bin/agentic-hooks.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# Universal Agentic Hooks Framework (UAHF) — Shell & Terminal Hooks
+# ==============================================================================
+# Ingests, normalizes, and governs all shell commands executed by interactive users,
+# terminal sessions, or agent subprocesses (Claude, Codex, Antigravity, Cursor, Kimi).
+# Handles pre-execution security and post-session Fable handoff compaction.
+# ==============================================================================
+
+export AGENTIC_HOOKS_ACTIVE=1
+PROJECT_DIR="${AGENTIC_PROJECT_DIR:-$(pwd)}"
+
+# 1. Intercepted Homebrew Wrapper
+brew() {
+  if [ -x "$PROJECT_DIR/bin/cli.js" ]; then
+    bun "$PROJECT_DIR/bin/cli.js" hooks brew-shim "$@"
+    return $?
+  elif command -v python3 >/dev/null 2>&1 && [ -f "$PROJECT_DIR/core/hooks/dispatcher.py" ]; then
+    python3 -c "from core.hooks.adapters.homebrew_adapter import HomebrewHookAdapter; import sys; sys.exit(HomebrewHookAdapter().run_shim(sys.argv[1:]))" "$@"
+    return $?
+  fi
+  # Fallback to standard brew if framework not reachable
+  command brew "$@"
+}
+
+# 2. Shell Command Interceptor (Zsh preexec / Bash DEBUG trap)
+__agentic_preexec_hook() {
+  local cmd="$1"
+  [ -z "$cmd" ] && return 0
+
+  # Fast-path: Skip evaluation for trivial builtins to maintain instant prompt speed
+  case "$cmd" in
+    cd*|pwd|echo*|printf*|true|false|test*|export*|unset*) return 0 ;;
+  esac
+
+  if command -v bun >/dev/null 2>&1 && [ -f "$PROJECT_DIR/bin/cli.js" ]; then
+    bun "$PROJECT_DIR/bin/cli.js" hooks dispatch --command "$cmd" --source terminal
+    local verdict=$?
+    if [ $verdict -ne 0 ]; then
+      return 1
+    fi
+  elif command -v python3 >/dev/null 2>&1 && [ -f "$PROJECT_DIR/core/hooks/dispatcher.py" ]; then
+    python3 -c "from core.hooks.adapters.shell_adapter import ShellHookAdapter; import sys; sys.exit(ShellHookAdapter().run_cli_preexec(sys.argv[1]))" "$cmd"
+    local verdict=$?
+    if [ $verdict -ne 0 ]; then
+      return 1
+    fi
+  fi
+  return 0
+}
+
+# 3. End of Session Hook & Fable Continuation State Compaction
+__agentic_session_end_hook() {
+  if [ -n "$AGENTIC_SESSION_FINALIZED" ]; then
+    return 0
+  fi
+  export AGENTIC_SESSION_FINALIZED=1
+
+  if command -v bun >/dev/null 2>&1 && [ -f "$PROJECT_DIR/bin/cli.js" ]; then
+    bun "$PROJECT_DIR/bin/cli.js" hooks session-end --agent terminal --reason shell_exit >/dev/null 2>&1
+  elif command -v python3 >/dev/null 2>&1 && [ -f "$PROJECT_DIR/core/hooks/session_end.py" ]; then
+    python3 -c "from core.hooks.session_end import SessionEndManager; SessionEndManager('${PROJECT_DIR}').handle_session_end(agent_id='terminal', reason='shell_exit')" >/dev/null 2>&1
+  fi
+}
+
+# 4. Zsh / Bash Bindings & Exit Trap
+trap __agentic_session_end_hook EXIT
+
+if [ -n "$ZSH_VERSION" ]; then
+  autoload -Uz add-zsh-hook 2>/dev/null
+  if command -v add-zsh-hook >/dev/null 2>&1; then
+    __agentic_zsh_preexec() {
+      __agentic_preexec_hook "$1"
+    }
+    add-zsh-hook preexec __agentic_zsh_preexec
+  fi
+fi
+
+echo "⚡ [UAHF] Agentic Shell & End-of-Session Hooks Activated (Project: $PROJECT_DIR)"