@mamdouh-aboammar/agentic-workflow 1.2.0

package/install.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# AgenticWorkflow Universal Cross-Platform Multi-Agent & Host Installer
+# Supports local execution or piped curl execution:
+#   curl -fsSL https://raw.githubusercontent.com/imMamdouhaboammar/agentic-workflow/main/install.sh | bash
+
+set -e
+
+TARGET_NAME="agentic-workflow"
+REPO_URL="https://github.com/imMamdouhaboammar/agentic-workflow.git"
+
+# Detect if executing via pipe or local script file
+if [ -n "${BASH_SOURCE[0]}" ] && [ -f "${BASH_SOURCE[0]}" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+else
+  # Remote curl execution: Clone into ~/.agentic-workflow
+  INSTALL_BASE="$HOME/.agentic-workflow"
+  echo "📥 Fetching latest AgenticWorkflow from ${REPO_URL}..."
+  if [ -d "$INSTALL_BASE/.git" ]; then
+    git -C "$INSTALL_BASE" pull --quiet
+  else
+    rm -rf "$INSTALL_BASE"
+    git clone --depth 1 "$REPO_URL" "$INSTALL_BASE" --quiet
+  fi
+  SCRIPT_DIR="$INSTALL_BASE"
+fi
+
+echo "================================================================="
+echo "⚡ Installing AgenticWorkflow across AI Agent Frameworks & Hosts"
+echo "================================================================="
+
+# 1. Claude Code
+if [ -d "$HOME/.claude" ] || command -v claude >/dev/null 2>&1; then
+  mkdir -p "$HOME/.claude/skills"
+  rm -rf "$HOME/.claude/skills/${TARGET_NAME}"
+  cp -r "$SCRIPT_DIR" "$HOME/.claude/skills/${TARGET_NAME}"
+  echo "  ✅ Installed for Claude Code -> $HOME/.claude/skills/${TARGET_NAME}"
+fi
+
+# 2. Antigravity / Gemini CLI
+if [ -d "$HOME/.gemini" ]; then
+  mkdir -p "$HOME/.gemini/config/skills"
+  rm -rf "$HOME/.gemini/config/skills/${TARGET_NAME}"
+  cp -r "$SCRIPT_DIR" "$HOME/.gemini/config/skills/${TARGET_NAME}"
+  echo "  ✅ Installed for Antigravity / Gemini CLI -> $HOME/.gemini/config/skills/${TARGET_NAME}"
+fi
+
+# 3. Cursor IDE
+if [ -d "$HOME/.cursor" ] || [ -d "$HOME/Library/Application Support/Cursor" ]; then
+  mkdir -p "$HOME/.cursor/skills"
+  rm -rf "$HOME/.cursor/skills/${TARGET_NAME}"
+  cp -r "$SCRIPT_DIR" "$HOME/.cursor/skills/${TARGET_NAME}"
+  echo "  ✅ Installed for Cursor -> $HOME/.cursor/skills/${TARGET_NAME}"
+fi
+
+# 4. Codex / OpenCode
+if [ -d "$HOME/.codex" ]; then
+  mkdir -p "$HOME/.codex/skills"
+  rm -rf "$HOME/.codex/skills/${TARGET_NAME}"
+  cp -r "$SCRIPT_DIR" "$HOME/.codex/skills/${TARGET_NAME}"
+  echo "  ✅ Installed for Codex / OpenCode -> $HOME/.codex/skills/${TARGET_NAME}"
+fi
+
+# 5. Universal Agent Kernel (~/.agents/skills)
+mkdir -p "$HOME/.agents/skills"
+rm -rf "$HOME/.agents/skills/${TARGET_NAME}"
+cp -r "$SCRIPT_DIR" "$HOME/.agents/skills/${TARGET_NAME}"
+echo "  ✅ Installed for Universal Agent Kernel -> $HOME/.agents/skills/${TARGET_NAME}"
+
+# 6. Global CLI Binary Symlink
+BIN_DIR="$HOME/.local/bin"
+mkdir -p "$BIN_DIR"
+CLI_TARGET="$SCRIPT_DIR/bin/cli.js"
+chmod +x "$CLI_TARGET"
+
+ln -sf "$CLI_TARGET" "$BIN_DIR/${TARGET_NAME}"
+echo "  ✅ Linked CLI executable -> $BIN_DIR/${TARGET_NAME}"
+
+# Also attempt /usr/local/bin if writable without sudo
+if [ -w "/usr/local/bin" ]; then
+  ln -sf "$CLI_TARGET" "/usr/local/bin/${TARGET_NAME}"
+  echo "  ✅ Linked CLI executable -> /usr/local/bin/${TARGET_NAME}"
+fi
+
+# 7. Provision Supportive Tools & Verify System Health
+echo ""
+echo "⚡ Provisioning supportive tools & frameworks (Ponytail, TOON, Fable, Caveman)..."
+if command -v python3 >/dev/null 2>&1; then
+  python3 -c "
+import sys
+sys.path.insert(0, '${SCRIPT_DIR}')
+try:
+    from core.integrations import IntegrationInstaller
+    IntegrationInstaller('${SCRIPT_DIR}').provision_all()
+except Exception as e:
+    print(f'Note: Supportive tools sync notice: {e}')
+" || true
+fi
+
+# 8. Run Doctor Diagnostic Check
+if command -v bun >/dev/null 2>&1; then
+  echo ""
+  echo "🩺 Verifying system health and toolchain invariants..."
+  bun "$CLI_TARGET" doctor || true
+fi
+
+echo ""
+echo "================================================================="
+echo "🎉 AgenticWorkflow successfully installed and ready everywhere!"
+echo "   Run 'agentic-workflow doctor' or 'agentic-workflow health'"
+echo "================================================================="
+

package/marketplace.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json.schemastore.org/claude-plugin-manifest.json",
+  "name": "agentic-workflow",
+  "displayName": "Agentic Workflow",
+  "version": "1.2.0",
+  "description": "Pluripotent stem-cell framework and universal agentic toolchain for autonomous workflows",
+  "author": {
+    "name": "Mamdouh Aboammar"
+  },
+  "homepage": "https://skills.sh/agentic-workflow",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imMamdouhaboammar/agentic-workflow.git"
+  },
+  "license": "MIT",
+  "categories": [
+    "automation",
+    "developer-tools",
+    "agent-tools",
+    "orchestration",
+    "skill-engine"
+  ],
+  "compatibility": {
+    "claudeCode": ">=1.0.0",
+    "claudeDesktop": ">=1.0.0",
+    "cursor": ">=0.40.0",
+    "codex": ">=0.1.0",
+    "chatgpt": ">=1.0.0",
+    "opencode": ">=1.0.0",
+    "antigravity": ">=1.0.0",
+    "geminiCli": ">=1.0.0"
+  },
+  "entrypoint": "SKILL.md",
+  "bin": {
+    "agentic-workflow": "./bin/cli.js"
+  }
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@mamdouh-aboammar/agentic-workflow",
+  "version": "1.2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Pluripotent stem-cell framework and universal agentic toolchain for autonomous workflows",
+  "type": "module",
+  "main": "bin/cli.js",
+  "module": "src/index.ts",
+  "types": "src/index.d.ts",
+  "bin": {
+    "agentic-workflow": "bin/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.ts",
+      "default": "./bin/cli.js"
+    },
+    "./engine": "./src/engine_ts/runner.ts",
+    "./hooks": "./src/hooks/dispatcher.ts",
+    "./integrations": "./src/integrations/index.ts",
+    "./toon": "./src/engine_ts/toon-adapter.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imMamdouhaboammar/agentic-workflow.git"
+  },
+  "homepage": "https://github.com/imMamdouhaboammar/agentic-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/imMamdouhaboammar/agentic-workflow/issues"
+  },
+  "files": [
+    "bin",
+    "core",
+    "src",
+    "docs",
+    "skills",
+    ".codex-plugin",
+    ".claude-plugin",
+    "SKILL.md",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md",
+    "soul.md",
+    "marketplace.json",
+    ".skills.json",
+    "install.sh"
+  ],
+  "scripts": {
+    "start": "bun bin/cli.js",
+    "test": "bun bin/cli.js test",
+    "validate": "bun bin/cli.js validate",
+    "status": "bun bin/cli.js status",
+    "prepack": "find . -name '__pycache__' -type d -prune -exec rm -rf {} + 2>/dev/null || true"
+  },
+  "keywords": [
+    "agentic-workflow",
+    "agent-skill",
+    "skills-sh",
+    "claude-code",
+    "antigravity",
+    "gemini-cli",
+    "cursor",
+    "codex",
+    "opencode",
+    "workflow-automation",
+    "multi-agent-systems",
+    "bun"
+  ],
+  "author": "Mamdouh Aboammar",
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.0.0",
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@toon-format/toon": "^4.1.1"
+  }
+}

package/skills/agentic-workflow/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/skills/agentic-workflow/skill-spec.json

@@ -0,0 +1,100 @@
+{
+  "name": "agentic-workflow",
+  "purpose": "Autonomous design, orchestration, validation, and execution of multi-step AI agent workflows across Research, Planning, and Implementation",
+  "baseline_failure": "Without guidance, AI agents produce incomplete plans, skip physical deliverable creation, mutate shared state concurrently, perform untested speculative edits, and fail to enforce deterministic quality gates across heterogeneous hosts",
+  "triggers": {
+    "positive": [
+      "build an autonomous pipeline",
+      "design agent workflow",
+      "execute in autopilot",
+      "run ulw mode",
+      "setup quality gates",
+      "run workflow",
+      "execute pipeline",
+      "start step"
+    ],
+    "negative": [
+      "format this json file",
+      "tell me a joke",
+      "write a simple one-line bash script",
+      "fix this single typo in README"
+    ]
+  },
+  "outputs": [
+    "SOT state.yaml with step-by-step progress",
+    "Stage deliverables verified on disk (L0-L2 quality gates)",
+    "pACS self-confidence delta evaluation log",
+    "Audit trace records in .traces and ledger"
+  ],
+  "invariants": [
+    "Absolute Criterion 1: Quality of the final deliverable strictly overrides speed and token costs",
+    "Absolute Criterion 2: Single-file SOT (state.yaml) with single-writer permission model",
+    "Absolute Criterion 3: Code Change Protocol (CCP) with 4 Coding Anchor Points (CAP-1~4)",
+    "Zero unexecuted assertions or fake mock approvals"
+  ],
+  "workflow": [
+    {
+      "action": "Research & intelligence gathering with domain expertise delegation",
+      "why": "Prevents building upon flawed or noisy requirements",
+      "freedom": "medium"
+    },
+    {
+      "action": "Architecture and verifiable plan formulation in SOT state.yaml",
+      "why": "Prevents architectural divergence and state desynchronization",
+      "freedom": "low"
+    },
+    {
+      "action": "Production implementation with surgical diffs and circuit breaker monitoring",
+      "why": "Prevents speculative thrashing and scope bloat",
+      "freedom": "low"
+    },
+    {
+      "action": "4-layer quality gate verification (L0 Anti-Skip, L1 Semantic Gate, L1.5 pACS, L2 Adversarial Review)",
+      "why": "Guarantees 100% functional goal achievement and deliverable integrity",
+      "freedom": "low"
+    }
+  ],
+  "tools": [
+    "read",
+    "write",
+    "patch",
+    "search",
+    "grep",
+    "shell",
+    "python"
+  ],
+  "resources": [
+    "state.yaml",
+    "core/autopilot_engine.py",
+    "core/engine_py/runner.py",
+    "src/engine_ts/runner.ts"
+  ],
+  "host_targets": [
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "chatgpt",
+    "antigravity",
+    "cursor"
+  ],
+  "evals": [
+    {
+      "name": "autopilot-pipeline-generation",
+      "prompt": "Design and execute an autonomous 3-stage pipeline for user onboarding",
+      "should_trigger": true,
+      "expected": [
+        "state.yaml initialized with 3 stages",
+        "L0 anti-skip verification passes for all deliverables",
+        "pACS score >= 70 recorded"
+      ]
+    },
+    {
+      "name": "negative-simple-edit",
+      "prompt": "Fix a spelling error in line 4 of index.html",
+      "should_trigger": false,
+      "expected": [
+        "Performs direct one-off edit without launching multi-agent workflow pipeline"
+      ]
+    }
+  ]
+}