agentic-workflow-toolchain 1.2.1__tar.gz

agentic_workflow_toolchain-1.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mamdouh Aboammar & Yoonsik Choi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentic_workflow_toolchain-1.2.1/PKG-INFO

@@ -0,0 +1,377 @@
+Metadata-Version: 2.4
+Name: agentic-workflow-toolchain
+Version: 1.2.1
+Summary: Pluripotent stem-cell framework and universal agentic toolchain for autonomous workflows
+Author: Mamdouh Aboammar
+License: MIT
+Project-URL: Homepage, https://github.com/imMamdouhaboammar/agentic-workflow
+Project-URL: Repository, https://github.com/imMamdouhaboammar/agentic-workflow.git
+Project-URL: Issues, https://github.com/imMamdouhaboammar/agentic-workflow/issues
+Keywords: agentic-workflow,agent-skill,skills-sh,claude-code,antigravity,gemini-cli,cursor,codex,opencode,workflow-automation,multi-agent-systems,autonomous-agents
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Dynamic: license-file
+
+<div align="center">
+
+# ⚡ AgenticWorkflow ⚡
+
+### Pluripotent Stem-Cell Framework & Universal Agentic Toolchain
+**Deterministic Quality Gates • Multi-Engine Autopilot • Single-File SOT • TOON v4.1 Density**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![Bun](https://img.shields.io/badge/Runtime-Bun%20%3E%3D1.0-FBF0DF?style=flat-square&logo=bun&logoColor=black)](https://bun.sh)
+[![Python](https://img.shields.io/badge/Python-%3E%3D3.10-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![npm](https://img.shields.io/badge/npm-agentic--workflow-CB3837?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/agentic-workflow)
+[![PyPI](https://img.shields.io/badge/PyPI-agentic--workflow-3775A9?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/agentic-workflow)
+[![Skills.sh](https://img.shields.io/badge/Skills.sh-Compatible-000000?style=flat-square&logo=vercel&logoColor=white)](https://skills.sh)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-Certified%20Skill-D97706?style=flat-square&logo=anthropic&logoColor=white)](https://claude.ai)
+[![Cursor](https://img.shields.io/badge/Cursor-Rules%20%26%20Skills-000000?style=flat-square&logo=cursor&logoColor=white)](https://cursor.com)
+[![CI](https://img.shields.io/badge/CI-Passing-10B981?style=flat-square&logo=githubactions&logoColor=white)](https://github.com/imMamdouhaboammar/agentic-workflow/actions)
+
+<p align="center">
+  <a href="#-universal-installation--quickstart">Quickstart</a> •
+  <a href="#1--one-click-agent-self-install--init-prompt">Agent Prompt</a> •
+  <a href="#-why-agenticworkflow-exists">Why It Exists</a> •
+  <a href="#-architecture">Architecture</a> •
+  <a href="#-dual-language-sdk-usage">SDK Usage</a> •
+  <a href="#-cli-reference">CLI Reference</a> •
+  <a href="#-supportive-tools">Supportive Tools</a> •
+  <a href="#-license">License</a>
+</p>
+
+</div>
+
+---
+
+## 🚀 Universal Installation & Quickstart
+
+AgenticWorkflow is packaged and distributable across every major package registry, AI harness, and container platform:
+
+### 1. 🤖 One-Click Agent Self-Install & Init Prompt
+
+Paste this prompt directly into your AI coding agent (Claude Code, Antigravity / Gemini CLI, Cursor, Codex, OpenCode, or Windsurf) to let it autonomously install, configure, initialize, and verify `AgenticWorkflow` in one shot:
+
+<details>
+<summary><b>👉 Click to expand the Smart Agent Prompts (Master Prompt & Quick-Fire)</b></summary>
+
+<br>
+
+> [!TIP]
+> **Copy & Paste into your Agent Chat:**
+
+````markdown
+You are acting as an autonomous DevOps & Systems Integration Agent. 
+Your objective is to install, configure, initialize, and verify the `agentic-workflow` framework in this workspace in a single uninterrupted execution loop.
+
+Execute the following 4 phases autonomously:
+
+### Phase 1: Universal Installation
+1. Detect available runtimes on the system (`python3`, `bun`, `npm`, `curl`, `git`).
+2. Run the universal one-line installer:
+   ```bash
+   curl -fsSL https://raw.githubusercontent.com/imMamdouhaboammar/agentic-workflow/main/install.sh | bash
+   ```
+   *(Fallback if offline or in a local clone: run `./install.sh` or `bun add -g agentic-workflow` / `npm install -g agentic-workflow`)*.
+3. Ensure `~/.local/bin` is in `$PATH` so the `agentic-workflow` CLI binary is immediately executable.
+
+### Phase 2: Host & Workspace Configuration
+1. Detect the current agent harness and verify registration in the appropriate skill directories:
+   - Claude Code: `~/.claude/skills/agentic-workflow`
+   - Gemini CLI / Antigravity: `~/.gemini/config/skills/agentic-workflow`
+   - Cursor: `~/.cursor/skills/agentic-workflow`
+   - Codex / OpenCode: `~/.codex/skills/agentic-workflow`
+   - Universal Agent Kernel: `~/.agents/skills/agentic-workflow`
+2. If this workspace lacks an `AGENTS.md` directive, link or import the AgenticWorkflow constitution (`AGENTS.md` and `GEMINI.md` / `CLAUDE.md`) so all subagents inherit:
+   - Absolute Criterion 1: Deliverable Quality over speed/token cost.
+   - Absolute Criterion 2: Single-File SOT (`state.yaml`) with single-writer lock.
+   - Absolute Criterion 3: Code Change Protocol (CCP: Understand Intent → Ripple Effect Analysis → Step Plan).
+   - 4-Layer Quality Assurance: L0 Anti-Skip → L1 Verification → L1.5 pACS Pre-mortem scoring → L2 Adversarial Review.
+3. Provision supportive tools by running:
+   ```bash
+   agentic-workflow integrations install
+   ```
+   Confirm integration of Ponytail (YAGNI & surgical diffs), TOON v4.1 (token compression), Fable (circuit breaker), and Caveman (concise mode).
+
+### Phase 3: Initialization (`init`)
+1. Run the native initialization command:
+   ```bash
+   agentic-workflow init
+   ```
+2. Confirm that:
+   - Runtime directories (`context-snapshots/`, `autopilot-logs/`, `diagnosis-logs/`) are generated.
+   - Core hook scripts in `.claude/hooks/scripts/` have validated syntax and execution permissions.
+   - The skills mesh index (`core/skills_indexer.py`) is indexed and queryable.
+
+### Phase 4: Validation & Status Report
+1. Verify the setup by running:
+   ```bash
+   agentic-workflow validate
+   agentic-workflow integrations status
+   ```
+2. Print a concise completion summary formatted in TOON v4.1 or a clean Markdown table showing CLI status, host skill registration paths, supportive tools readiness, and quality gates status.
+
+Proceed and execute all steps now without stopping for manual input.
+````
+
+#### ⚡ Quick-Fire Version
+```text
+Run the universal installer for AgenticWorkflow (`curl -fsSL https://raw.githubusercontent.com/imMamdouhaboammar/agentic-workflow/main/install.sh | bash`), link CLI to PATH, run `agentic-workflow init` to configure SOT runtime and supportive tools (Ponytail, TOON, Fable, Caveman), and run `agentic-workflow validate` to confirm 100% readiness. Report the final status table when done.
+```
+
+</details>
+
+### 2. Agent Skill Hubs (Zero-Install Agent Registration)
+
+```bash
+# Skills.sh / Vercel Ecosystem (Any Agent)
+npx skills add imMamdouhaboammar/agentic-workflow
+
+# Universal One-Line Installer (Claude, Gemini, Cursor, Codex, OpenCode)
+curl -fsSL https://raw.githubusercontent.com/imMamdouhaboammar/agentic-workflow/main/install.sh | bash
+```
+
+### 3. Package Managers (CLI & SDK)
+
+| Registry / Host | Command | Usage |
+|---|---|---|
+| **Bun (Instant CLI)** | `bunx @mamdouh-aboammar/agentic-workflow [command]` | Zero-install CLI execution |
+| **Bun (Library)** | `bun add @mamdouh-aboammar/agentic-workflow` | TypeScript / Bun SDK dependency |
+| **npm / npx (Node)** | `npx @mamdouh-aboammar/agentic-workflow [command]` | Zero-install Node CLI execution |
+| **npm (Library)** | `npm install @mamdouh-aboammar/agentic-workflow` | Node.js ESM library dependency |
+| **PyPI (Python)** | `pip install agenticworkflow` | Python library & console script |
+| **Homebrew (macOS/Linux)** | `brew install imMamdouhaboammar/tap/agentic-workflow` | System binary via Homebrew |
+| **Docker Container** | `docker run -it ghcr.io/immamdouhaboammar/agentic-workflow` | Isolated, containerized runner |
+
+---
+
+## ⚡ Why AgenticWorkflow Exists
+
+Most AI workflows fail in production due to three compounding traps:
+1. **Hallucinated Progress**: Agents mark tasks complete without verifying actual deliverables on disk.
+2. **Context Amnesia**: Sessions reset or compact, losing critical context and historical failures.
+3. **Unchecked Drift**: Multi-agent swarms mutate shared state simultaneously, causing race conditions and logic divergence.
+
+AgenticWorkflow eliminates these failure modes with a 2-stage execution model backed by deterministic Python and TypeScript safety rails:
+
+```mermaid
+flowchart LR
+    Phase1["Phase 1: Workflow Design (workflow.md blueprint)"] --> Phase2["Phase 2: Workflow Implementation (Executing Autonomous System)"]
+```
+
+Creating `workflow.md` is only half the journey. **The ultimate goal is that the workflow executes reliably and produces verified deliverables.**
+
+---
+
+## 🏛️ 3-Stage Core Architecture
+
+Every workflow strictly follows three sequential stages:
+
+```mermaid
+graph TD
+    subgraph ResearchStage ["1. Research Stage"]
+        R1["Information Gathering"] --> R2["Domain Analysis & Fact Verification"]
+    end
+
+    subgraph PlanningStage ["2. Planning Stage"]
+        P1["State Formulation (state.yaml SOT)"] --> P2["Human / Autopilot Review & Approval"]
+    end
+
+    subgraph ImplementationStage ["3. Implementation Stage"]
+        I1["Autonomous Execution & Tool Orchestration"] --> I2["4-Layer Quality Gates & Final Deliverables"]
+    end
+
+    ResearchStage --> PlanningStage
+    PlanningStage --> ImplementationStage
+```
+
+1. **Research** — Information gathering, competitive benchmarking, and deep domain analysis.
+2. **Planning** — Architecture blueprint formulation, task decomposition, and human/autopilot sign-off.
+3. **Implementation** — Multi-agent tool execution, code generation, and artifact verification.
+
+---
+
+## 🛡️ 4-Layer Quality Assurance Stack
+
+Every step completion must pass up to 4 verification layers before the Orchestrator advances the Single Source of Truth (`state.yaml`):
+
+```mermaid
+flowchart TD
+    StepRun["Agent Executes Step Task"] --> L0["L0: Anti-Skip Physical Guard (File exists & >= 100 bytes)"]
+    L0 -->|"PASS"| L1["L1: Verification Gate (100% functional goal achievement)"]
+    L0 -->|"FAIL"| Retry["Deterministic Retry / Diagnosis"]
+    L1 -->|"PASS"| L15["L1.5: pACS Self-Rating (F/C/L Pre-mortem scoring)"]
+    L1 -->|"FAIL"| Retry
+    L15 -->|"RED: <50"| Retry
+    L15 -->|"GREEN / YELLOW"| L2["L2: Adversarial Review (@reviewer + @fact-checker)"]
+    L2 -->|"PASS"| SOTUpdate["Update SOT state.yaml (current_step + 1)"]
+    L2 -->|"FAIL"| AbductiveDiag["Abductive Diagnosis (diagnose_context.py)"]
+    AbductiveDiag --> Retry
+```
+
+| Layer | Gate Name | Target Verified | Mechanism |
+|---|---|---|---|
+| **L0** | Anti-Skip Guard | Physical deliverable exists and size $\ge 100$ bytes | Deterministic Python hook |
+| **L1** | Verification Gate | 100% achievement of declared task acceptance criteria | Semantic agent self-verification |
+| **L1.5** | pACS Calibration | 3D confidence scoring (Faithfulness, Completeness, Logic) | Pre-mortem protocol ($\min(F, C, L)$) |
+| **L2** | Adversarial Review | Independent critique, claim audit, and web fact-checking | `@reviewer` + `@fact-checker` subagents |
+
+---
+
+## 💻 Dual-Language SDK Usage
+
+### TypeScript & Bun (`npm install agentic-workflow` or `bun add agentic-workflow`)
+
+```typescript
+import { 
+  AutopilotEngine, 
+  HookDispatcher, 
+  IntegrationInstaller, 
+  encodeToon, 
+  calculateTokenSavings 
+} from 'agentic-workflow';
+
+// 1. Token-Oriented Object Notation (v4.1) compression
+const data = {
+  users: [
+    { id: 1, name: "Alice", role: "architect" },
+    { id: 2, name: "Bob", role: "reviewer" }
+  ]
+};
+const toonData = encodeToon(data);
+console.log(`Compressed TOON:\n${toonData}`);
+
+// 2. Hook Dispatcher evaluation
+const dispatcher = new HookDispatcher(process.cwd());
+const check = dispatcher.dispatch({
+  event_id: "evt_1",
+  source: "cli",
+  hook_type: "pre_command",
+  timestamp: Date.now(),
+  command: "git status"
+});
+console.log(`Hook verdict: ${check.verdict}`);
+```
+
+### Python (`pip install agentic-workflow`)
+
+```python
+from agentic_workflow import (
+    AutopilotEngine, 
+    HookDispatcher, 
+    IntegrationInstaller,
+    CleanCodeChecker,
+    MultiAgentManager
+)
+
+# 1. Launch Autopilot Engine
+engine = AutopilotEngine(project_dir=".", auto_approve=True)
+engine.plan_default_workflow(
+    title="Data Ingestion Pipeline", 
+    goal="Autonomous end-to-end data ingestion with quality gates"
+)
+success = engine.run_all()
+
+# 2. Check Supportive Tools Status
+installer = IntegrationInstaller(project_dir=".")
+results = installer.check_all()
+for r in results:
+    print(f"- {r.name}: {r.status}")
+```
+
+---
+
+## ⚙️ CLI Reference
+
+```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
+
+# Manage supportive tools (Ponytail, TOON, Fable, Caveman) & lifecycle
+agentic-workflow integrations status
+agentic-workflow integrations install
+agentic-workflow integrations phase planning
+
+# Token-Oriented Object Notation (v4.1) benchmarks and conversion
+agentic-workflow toon benchmark
+agentic-workflow toon convert <file.json>
+
+# Initialize infrastructure, SOT runtime directories, and supportive tools
+agentic-workflow init
+
+# Validate workflow.md, SOT schema, and pACS integrity
+agentic-workflow validate
+
+# Check current workflow progress and observability dashboard
+agentic-workflow status
+
+# Run full automated test suite (16 suites: safety, guard, MAS, engines, integrations)
+agentic-workflow test
+```
+
+---
+
+## 🧰 Supportive Tools Ecosystem
+
+AgenticWorkflow automatically provisions and directs specialized supportive tools across its execution phases without manual user overhead:
+
+| Supportive Tool | Role & Category | Designated Lifecycle Phase |
+|---|---|---|
+| **[Ponytail](https://github.com/DietrichGebert/ponytail)** | **Simplicity Governor & Anti-Debt** | **Planning & Implementation**: Enforces YAGNI ladder, stdlib-first, and shortest working surgical diffs. |
+| **[TOON](https://github.com/toon-format/toon)** | **Token-Oriented Object Notation (v4.1)** | **Continuous Data Protocol**: Cuts structured data and state tokens by 30-60% across all deliverables and logs. |
+| **[Fable](https://github.com/imMamdouhaboammar/get-fable)** | **Lifecycle Harness & Continuation** | **Execution & Handoff**: Arms circuit breakers (halts on failure streak $\ge 2$) and generates durable continuation state (`.fable/`). |
+| **[Caveman](https://github.com/JuliusBrussee/caveman)** | **Terse Communication Mode** | **Continuous Protocol**: Strips conversational fluff to cut output tokens by 65-75% while keeping code and errors exact. |
+
+---
+
+## 📜 Absolute Criteria (Canon)
+
+These constitutional rules govern every design, execution, and modification decision:
+
+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 workflow state is concentrated in a single file (`state.yaml`). 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, you must perform **Step 1 (Understand Intent) → Step 2 (Ripple Effect Analysis) → Step 3 (Change Plan)**. Governed by Coding Anchor Points (CAP-1~4).
+
+---
+
+## 📖 Documentation Roadmap
+
+1. **README.md** (This document) — High-level bird's-eye overview and distribution hub.
+2. [`soul.md`](soul.md) — The philosophical core and DNA inheritance principles.
+3. [`AGENTICWORKFLOW-ARCHITECTURE-AND-PHILOSOPHY.md`](AGENTICWORKFLOW-ARCHITECTURE-AND-PHILOSOPHY.md) — Architectural design and theoretical foundations.
+4. [`DECISION-LOG.md`](DECISION-LOG.md) — Complete historical record of architectural decisions (ADRs).
+5. [`AGENTICWORKFLOW-USER-MANUAL.md`](AGENTICWORKFLOW-USER-MANUAL.md) — Practical step-by-step operating instructions.
+6. [`AGENTS.md`](AGENTS.md) — Universal directive and constitutional rules.
+7. [`docs/protocols/`](docs/protocols/) — Deep-dive execution protocols.
+
+---
+
+## 📄 License
+
+MIT License © 2026 Mamdouh Aboammar & Yoonsik Choi. All rights reserved.