@mamdouh-aboammar/agentic-workflow 1.2.0

package/CLAUDE.md

@@ -0,0 +1,178 @@
+# AgenticWorkflow
+
+Claude Code-based agent workflow automation project.
+
+## Final Goal
+
+1. **Workflow Design**: Systematically design complex tasks into a 3-stage `workflow.md` (Research → Planning → Implementation).
+2. **Workflow Execution**: Actually implement the agents, scripts, and automation pipeline configured in `workflow.md`.
+
+> Designing `workflow.md` is an intermediate blueprint. **Ensuring the workflow actually executes and produces verified deliverables** is the final goal.
+
+### Purpose of Existence — DNA Inheritance
+
+AgenticWorkflow is a **parent organism that gives birth to child agentic workflow systems**. The `workflow-generator` skill serves as the production line, and every child system **structurally embeds** the parent genome (Constitution, Structure, Verification, Safety, Memory, Adversarial Criticism, and Transparency). Details: `soul.md §0`.
+
+## Absolute Criteria
+
+> The top-level rules applied to every design, implementation, and modification decision. These supersede all guidelines and principles below.
+
+### 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**.
+
+### Absolute Criterion 2: Single-File SOT + Hierarchical Memory Structure
+> All shared state is concentrated in a single file (`state.yaml`). SOT write permission belongs exclusively to the Orchestrator / Team Lead. Concurrent modification of the same file by parallel agents is strictly prohibited.
+
+### Absolute Criterion 3: Code Change Protocol (CCP)
+> Before writing, modifying, adding, or deleting code, you must internally perform **Step 1 (Understand Intent) → Step 2 (Ripple Effect Analysis) → Step 3 (Change Plan)**. Analysis depth scales with change scope. **Details**: `docs/protocols/code-change-protocol.md`.
+
+**Coding Anchor Points (CAP)**: CAP-1 (Think Before Coding), CAP-2 (Simplicity First), CAP-3 (Goal-Based Execution), CAP-4 (Surgical Changes). When conflicting with Absolute Criterion 1, Quality always wins.
+
+### Priority Among Absolute Criteria
+> **Absolute Criterion 1 (Quality) is paramount.** Absolute Criterion 2 (SOT) and Absolute Criterion 3 (CCP) are co-equal means to guarantee quality.
+
+### TOON Style Enforcement (v4.1)
+> **All agents and Claude sessions MUST enforce TOON (Token-Oriented Object Notation v4.1) on structured responses, dialogues, and deliverables**, achieving 30–60% token savings over JSON/markdown tables. Reference: `AGENTS.md §5.7`.
+
+---
+
+## Project Structure
+
+```
+AgenticWorkflow/
+├── CLAUDE.md                        ← This file (Claude Code directive — lightweight TOC)
+├── AGENTS.md                        ← Universal AI agent common directive (Hub — methodology SOT)
+├── GEMINI.md                        ← Gemini CLI / Antigravity directive (Spoke)
+├── soul.md                          ← DNA inheritance definition
+├── DECISION-LOG.md                  ← Architecture Decision Records (ADR, 51+ records)
+├── AGENTICWORKFLOW-USER-MANUAL.md   ← User manual
+├── AGENTICWORKFLOW-ARCHITECTURE-AND-PHILOSOPHY.md ← Design philosophy and architectural bird's-eye view
+├── docs/protocols/                  ← Detailed protocols (on-demand references)
+│   ├── autopilot-execution.md       (Workflow execution checklist + NEVER DO)
+│   ├── quality-gates.md             (L0-L2 4-layer + P1 14-item validation details)
+│   ├── ulw-mode.md                  (ULW 3 intensifier rules + runtime mechanics)
+│   ├── context-preservation-detail.md (Hook internal mechanics + D-7 instances)
+│   └── code-change-protocol.md      (CCP 3 steps + CAP + Proportionality Rule)
+├── .claude/
+│   ├── settings.json                ← Hook configuration
+│   ├── agents/
+│   │   ├── translator.md            (Terminology consistency specialist)
+│   │   ├── reviewer.md              (Adversarial reviewer, Enhanced L2)
+│   │   └── fact-checker.md          (Fact-checker, claim-by-claim verification)
+│   ├── commands/
+│   │   ├── install.md               (/install — Setup Init validation)
+│   │   └── maintenance.md           (/maintenance — Health check)
+│   ├── hooks/scripts/               ← Hook + validation scripts
+│   │   ├── context_guard.py         (Unified dispatcher)
+│   │   ├── _context_lib.py          (Shared library — parsing, generation, validation, compression)
+│   │   ├── save_context.py          (SessionEnd/PreCompact snapshot persistence)
+│   │   ├── restore_context.py       (SessionStart restore + RLM pointers)
+│   │   ├── update_work_log.py       (PostToolUse 9 tools tracking)
+│   │   ├── generate_context_summary.py (Stop incremental snapshot + safety net)
+│   │   ├── diagnose_context.py      (Abductive Diagnosis pre-analysis)
+│   │   ├── validate_diagnosis.py    (AD1-AD10 post-validation)
+│   │   ├── validate_pacs.py         (PA1-PA7 + L0 validation)
+│   │   ├── validate_review.py       (R1-R5 review validation)
+│   │   ├── validate_traceability.py (CT1-CT5 traceability validation)
+│   │   ├── validate_domain_knowledge.py (DK1-DK7 domain knowledge validation)
+│   │   ├── validate_translation.py  (T1-T9 translation & glossary validation)
+│   │   ├── validate_verification.py (V1a-V1c verification log validation)
+│   │   ├── validate_workflow.py     (W1-W8 DNA inheritance validation)
+│   │   ├── validate_retry_budget.py (RB1-RB3 retry budget decision)
+│   │   ├── setup_init.py            (Infrastructure health check + SOT write pattern check)
+│   │   ├── setup_maintenance.py     (Periodic health check + doc-code sync)
+│   │   ├── block_destructive_commands.py (Dangerous command blocking: network/system/git/rm, exit 2)
+│   │   ├── block_test_file_edit.py  (TDD Guard, .tdd-guard toggle)
+│   │   ├── predictive_debug_guard.py (Risk file warning based on error history, exit 0)
+│   │   ├── output_secret_filter.py  (Secret detection: 3-tier, 25+ regexes, 2-pass scan)
+│   │   ├── security_sensitive_file_guard.py (Security sensitive file modification warning)
+│   │   ├── query_workflow.py        (Workflow observability: dashboard/weakest/retry/blocked)
+│   │   ├── _test_secret_filter.py   (output_secret_filter tests — 44 cases)
+│   │   ├── _test_sensitive_file_guard.py (security_sensitive_file_guard tests — 44 cases)
+│   │   └── _test_block_destructive.py (block_destructive_commands tests — 43 cases)
+│   ├── context-snapshots/           ← Runtime snapshots (gitignored)
+│   └── skills/
+│       ├── workflow-generator/      (Workflow design & generation skill)
+│       └── doctoral-writing/        (Doctoral academic writing skill)
+├── translations/glossary.yaml       ← Terminology glossary
+├── prompt/                          ← PRD investigation frameworks & agent prompts
+└── coding-resource/                 ← Theoretical foundations
+```
+
+## Context Preservation System
+
+An automatic persistence and recovery system that prevents loss of work context upon context token exhaustion, `/clear`, or compaction.
+
+| Hook Event | Script | Action |
+|---|---|---|
+| Setup (`--init`) | `setup_init.py` | Infrastructure health check + SOT write safety + runtime directory init |
+| Setup (`--maintenance`) | `setup_maintenance.py` | Periodic health check + doc-code synchronization |
+| PreToolUse (Bash) | `block_destructive_commands.py` | Blocks dangerous commands: network exfil, raw format, git reset/force, rm -rf (exit 2) |
+| PreToolUse (Edit\|Write) | `block_test_file_edit.py` | Protects test files during active TDD Guard (exit 2) |
+| PreToolUse (Edit\|Write) | `predictive_debug_guard.py` | Warns on high-risk files based on past failure history |
+| SessionStart | `restore_context.py` | RLM pointers + past session index + Predictive Debugging risk cache |
+| PostToolUse (9 tools) | `update_work_log.py` | Accumulates granular tool usage logs |
+| PostToolUse (Bash\|Read) | `output_secret_filter.py` | Detects leaked secrets (3-tier extraction, 2-pass scan) |
+| PostToolUse (Edit\|Write) | `security_sensitive_file_guard.py` | Warns on security-sensitive file changes |
+| Stop | `generate_context_summary.py` | Incremental snapshot + Knowledge Archive indexing + safety net |
+| PreCompact | `save_context.py` | Saves full snapshot before context compaction |
+| SessionEnd | `save_context.py` | Saves full snapshot on `/clear` or session exit |
+
+**Mandatory Action**: When `[CONTEXT RECOVERY]` appears at session start, **you must read the indicated snapshot file** via Read tool to restore prior working context.
+
+**Details**: Hook internal mechanics, Knowledge Archive schema, and D-7 instances → `docs/protocols/context-preservation-detail.md`.
+
+## Skill Invocation Routing
+
+| User Request Pattern | Skill | Entry Point |
+|---|---|---|
+| "create workflow", "design automation pipeline", "build workflow" | `workflow-generator` | SKILL.md |
+| "write in doctoral style", "academic writing", "dissertation polish" | `doctoral-writing` | SKILL.md |
+
+## Core Design Principles
+
+1. **P1 — Data Refinement for Accuracy**: Strip noise deterministically via Python code before handing off to AI agents.
+2. **P2 — Expertise-Based Delegation Structure**: Delegate specialized tasks to domain agents; Orchestrator focuses on coordination.
+3. **P3 — Resource Accuracy**: Explicit paths for all files, dependencies, and external assets; placeholders are forbidden.
+4. **P4 — Question Design Rules**: Maximum 4 questions, each with ~3 options. Proceed without questions if unambiguous.
+
+## Autopilot Mode
+
+Autonomous execution mode that auto-approves `(human)` review stages and questions. Details: `AGENTS.md §5.1`.
+
+**4-Layer Quality Assurance**: L0 (Anti-Skip Guard) → L1 (Verification Gate) → L1.5 (pACS Self-Scoring) → L2 (Adversarial Review). Details: `docs/protocols/quality-gates.md`.
+
+**Required Reading Before Execution**: `docs/protocols/autopilot-execution.md` — step-by-step checklist and NEVER DO rules.
+
+## ULW (Ultrawork) Mode
+
+Activated whenever `ulw` is present in the prompt. Acts as an **intensity overlay on rigor**. Orthogonal to Autopilot. 3 Intensifiers: I-1 (Sisyphus Persistence), I-2 (Mandatory Task Decomposition), I-3 (Bounded Retry Escalation).
+
+**Details**: `docs/protocols/ulw-mode.md`.
+
+## Supportive Tools Ecosystem & Sequential Operational Lifecycle
+
+The system automatically provisions and orchestrates supportive tools:
+- **Continuous Layer**: **TOON v4.1** for structured data exchange and **Caveman** mode for concise, zero-slop agent reasoning and logs.
+- **Phase 2 (Architecture & Planning)**: **Ponytail YAGNI Ladder** (Rung 1-3: question speculative code, stdlib-first, reuse existing patterns) + **Fable Plan**.
+- **Phase 3 (Implementation)**: **Ponytail Surgical Diffs** (Rung 4-7: fewest files, shortest diff, root cause fix) + **Fable Circuit Breaker** (halt if failure streak >= 2).
+- **Phase 4 (Verification)**: Clean Code Guard + Ponytail Anti-Debt audit + L0-L2 quality gates.
+- **Phase 5 (Handoff)**: Compact session into durable continuation state (`.fable/state.json`, `.fable/PROGRESS.md`).
+
+Details: `AGENTS.md §5.8`.
+
+## Language and Style Rules
+
+- **Framework Documentation & User Dialogue**: Pure English
+- **Workflow Execution**: Pure English (maximizes AI reasoning capability — Absolute Criterion 1)
+- **Deliverables**: English primary deliverables
+- **Technical Terminology**: Maintain standard English terms (SOT, Agent Team, Hooks, pACS, etc.)
+- **Visualization**: Prefer clean Mermaid diagrams with quoted labels
+- **Depth**: Comprehensive, data-backed exposition over superficial summaries
+
+## Skill Development Rules
+
+1. **Embed all Absolute Criteria** — contextualized for the target domain.
+2. **Strict division of file responsibilities** — `SKILL.md` (WHY / Routing), `references/` (WHAT / HOW / VERIFY).
+3. **Explicit conflict resolution scenarios** among Absolute Criteria.
+4. Always reflect and audit against the Absolute Criteria after any modification.

package/GEMINI.md

@@ -0,0 +1,102 @@
+# AgenticWorkflow — Gemini CLI Directive
+
+> All AI agents working on this project must follow the AgenticWorkflow methodology.
+
+## Essential References
+
+@AGENTS.md
+
+The above document defines all Absolute Criteria, design principles, and workflow structures for this project.
+Refer to `AGENTICWORKFLOW-ARCHITECTURE-AND-PHILOSOPHY.md` for architectural design and rationale.
+Refer to `DECISION-LOG.md` for historical design decisions (ADRs).
+
+## Genetic Design (DNA Inheritance)
+
+This project is a parent organism that births child agentic workflow systems.
+Every child system structurally embeds the parent genome: 3 Absolute Criteria, Single-File SOT, 4-Layer Verification, Safety Hooks, and Memory Systems.
+Details: `soul.md`, `AGENTS.md §1`.
+
+## Absolute Criteria (Core Summary)
+
+### 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**.
+
+### Absolute Criterion 2: Single-File SOT
+> All shared state is concentrated in a single file (`state.yaml`). Write permission is held exclusively by the Orchestrator / Team Lead. Parallel agents concurrently modifying the same file is strictly prohibited.
+
+### Absolute Criterion 3: Code Change Protocol (CCP)
+> Before writing, modifying, adding, or deleting code, you must internally perform 3 steps:
+> Step 1: Understand Intent → Step 2: Ripple Effect Analysis → Step 3: Change Plan.
+> Analysis depth scales proportionally with change scope (Minor: Step 1 only, Standard: full 3 steps, Large-scale: full 3 steps + mandatory user approval).
+> **Coding Anchor Points (CAP-1~4)**: Think Before Coding, Simplicity First, Goal-Based Execution, Surgical Changes. Details: `AGENTS.md §2`.
+
+## Basic Workflow Structure
+
+Every workflow consists of three stages:
+1. **Research** — Information gathering and analysis
+2. **Planning** — Plan formulation, structuring, human review and approval
+3. **Implementation** — Actual execution and verified deliverable generation
+
+## Gemini CLI Implementation Mapping
+
+| AgenticWorkflow Concept | Gemini CLI Implementation |
+|---|---|
+| Specialized Agent (Sub-agent) | Gemini CLI is a single-session model. Simulate domain expertise by switching roles within the prompt or using subagents. |
+| Agent Group (Agent Team) | Parallel Gemini CLI / Antigravity subagent sessions coordinated by Orchestrator. |
+| Automated Verification (Hooks) | External Python and shell scripts executing automated verification pipelines. |
+| Reusable Modules (Skills) | Injected via `@file.md` imports or skills directory. |
+| External Integration (MCP) | Gemini extensions or external API scripts. |
+| SOT State Management | `state.yaml` file — single write point principle applies identically. |
+| Autopilot Mode | Controlled by `autopilot.enabled` field in SOT. Auto-approves `(human)` review steps. Includes Anti-Skip Guard and Decision Logs (`autopilot-logs/`). See `AGENTS.md §5.1`. |
+| ULW (Ultrawork) Mode | Activated when `ulw` is present in prompt. Thoroughness intensity overlay orthogonal to Autopilot. 3 Intensifiers: Sisyphus Persistence (3 retries), Mandatory Task Decomposition, Bounded Retry Escalation. See `AGENTS.md §5.1.1`. |
+| Verification Protocol | Verifies 100% functional goal achievement of step deliverables. Verification Gate layer sitting atop physical Anti-Skip Guard. Retries up to 10 times (15 with ULW). See `AGENTS.md §5.3`. |
+| pACS (Self-Confidence Scoring) | 3-dimensional self-evaluation (Faithfulness, Completeness, Logic) with mandatory Pre-mortem protocol and min-score principle. GREEN (>=70): proceed, YELLOW (50-69): flag and proceed, RED (<50): rework. See `AGENTS.md §5.4`. |
+| Adversarial Review (Enhanced L2) | Independent evaluation replacing legacy calibration. `@reviewer` (critical analysis of code/deliverables, read-only) + `@fact-checker` (external fact verification, web access). P1 validation (`validate_review.py`) ensures review rigor. See `AGENTS.md §5.5`. |
+| Terminology Protocol | Maintains terminology consistency via `translations/glossary.yaml`. Deterministic validation guarantees glossary freshness and integrity. See `AGENTS.md §5.2`. |
+| Predictive Debugging (L-1) | Pre-tool warning on risky files based on error history. `predictive_debug_guard.py` (PreToolUse warning) + `aggregate_risk_scores()` (SessionStart P1 aggregation) + `validate_risk_scores()` (RS1-RS6 validation). Cached in `risk-scores.json`. |
+| Abductive Diagnosis | 3-step structured diagnosis triggered on quality gate failure before retry: Step A: P1 evidence gathering (`diagnose_context.py`), Step B: Multi-hypothesis root cause analysis, Step C: P1 post-validation (`validate_diagnosis.py` AD1-AD10). Recorded in `diagnosis-logs/`. See `AGENTS.md §5.6`. |
+| TOON Protocol (v4.1) | Mandatory Token-Oriented Object Notation for structured outputs, dialogues, logs, and agent payloads. Saves 30-60% tokens. Dual engine adapters (`core/engine_py/toon_adapter.py`, `src/engine_ts/toon-adapter.ts`). See `AGENTS.md §5.7`. |
+| Supportive Tools & Lifecycle Director | Automated provisioning & sequential execution of Ponytail, TOON, Fable, and Caveman without manual user burden. Managed by `LifecycleDirector` and `IntegrationInstaller`. See `AGENTS.md §5.8`. |
+
+## Sequential Operational Lifecycle & Supportive Tools
+
+In every Gemini CLI / Antigravity session, the agent operates under the automated guidance of the **Sequential Operational Lifecycle Director**:
+1. **Continuous Layer**: Enforce **TOON v4.1** for structured data tables/state and **Caveman** mode (terse, zero-slop prose) for internal logs and agent dialogue.
+2. **Phase 2 (Architecture & Planning)**: Enforce **Ponytail YAGNI Ladder** (Rung 1-3: question speculative requirements, stdlib-first, reuse existing patterns) before finalizing any plan.
+3. **Phase 3 (Production Implementation)**: Enforce **Ponytail Surgical Diffs** (Rung 4-7: fewest files, shortest diff, root cause fix) + **Fable Circuit Breaker** (halt if failure streak >= 2).
+4. **Phase 4 (Verification)**: Clean Code Guard + Ponytail Anti-Debt audit + L0-L2 quality gates.
+5. **Phase 5 (Handoff)**: Compact session into durable continuation state (`.fable/state.json`, `.fable/PROGRESS.md`).
+
+## TOON Response & Conversation Invariant
+
+When working within this system, Gemini CLI / Antigravity MUST emit structured information (lists, tables, benchmarks, telemetry, status reports) formatted in **TOON v4.1** syntax instead of verbose JSON or markdown tables to maximize context headroom.
+
+```toon
+tasks[2]{id,agent,status}:
+  1,researcher,completed
+  2,engineer,in_progress
+```
+
+## Context Preservation
+
+In environments without automatic Claude Code hook dispatching:
+- **Manual Snapshot**: Direct the agent to save progress to `context-snapshot.md`.
+- **Session Memory**: Utilize agent memory mechanisms to track core architectural state.
+- **SOT-Based Recovery**: Restore workflow state seamlessly by reading `state.yaml`.
+
+## Core Design Principles
+
+- **P1**: Remove noise via deterministic scripts before passing context to AI.
+- **P2**: Maximize quality through specialized delegation.
+- **P3**: Explicit paths for all resources; no placeholders.
+- **P4**: User questions: maximum 4, ~3 options each. If unambiguous, proceed without questions.
+
+## Language and Style Rules
+
+- **Framework Documentation & User Dialogue**: Pure English
+- **Workflow Execution**: Pure English (maximizes reasoning performance — Absolute Criterion 1)
+- **Deliverables**: English primary deliverables
+- **Technical Terminology**: Keep standard English terms (SOT, Agent, Orchestrator, Hooks, etc.)
+- **Visualization**: Prefer clean Mermaid diagrams with quoted labels
+- **Depth**: Comprehensive, data-backed exposition over superficial summaries

package/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.

package/README.md

@@ -0,0 +1,350 @@
+<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.