awf 1.0.0__tar.gz

awf-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EnerJize
+
+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.

awf-1.0.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: awf
+Version: 1.0.0
+Summary: Agentic Workflow Framework — declarative multi-agent pipeline orchestrator for opencode
+Author: EnerJize
+License: MIT
+Project-URL: Homepage, https://github.com/EnerJizeIT/agentic-workflow
+Project-URL: Repository, https://github.com/EnerJizeIT/agentic-workflow
+Project-URL: Issues, https://github.com/EnerJizeIT/agentic-workflow/issues
+Keywords: opencode,mcp,ai-agent,pipeline,multi-agent,orchestrator,workflow
+Classifier: Development Status :: 4 - Beta
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: markdown>=3.4
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.0; extra == "dev"
+Dynamic: license-file
+
+# Agentic Workflow (awf)
+
+[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![tests](https://github.com/EnerJizeIT/agentic-workflow/actions/workflows/test.yml/badge.svg)](https://github.com/EnerJizeIT/agentic-workflow/actions/workflows/test.yml)
+
+> **Multi-agent pipeline orchestrator for opencode. Plan → build → verify → commit — through typed MCP tools, not bash.**
+
+## The problem it solves
+
+AI coding agents are powerful but chaotic. They jump straight to code without planning, skip review, leave bugs. You watch helplessly as tokens burn.
+
+**awf** adds structure: a supervisor agent plans the work, worker agents execute through a pipeline you design (any roles, any depth — from a single worker to a multi-stage chain), and you approve each result before it commits. All through natural language — *"start working on the backlog"*, *"verify and approve"*, *"reject — the DOMParser fix is missing"*.
+
+You stay in control. The agent stays on rails.
+
+## Quick Start
+
+```bash
+# 1. Install
+pip install -e .
+pip install -e ./agent_workflow_ui
+
+# 2. Configure opencode — add to ~/.config/opencode/opencode.json:
+# {
+#   "mcp": {
+#     "agent-workflow-ui": {
+#       "type": "local",
+#       "command": ["python3", "-m", "agent_workflow_ui"],
+#       "enabled": true
+#     }
+#   }
+# }
+
+# 3. Run — just talk to opencode:
+# "Initialize awf in my project"
+# "Develop the MVP based on the backlog"
+```
+
+## Requirements
+
+| Component | Requirement |
+|---|---|
+| **Python** | 3.10+ |
+| **opencode** | any recent version with MCP support |
+| **OS** | Linux (tested), macOS (should work), Windows (untested) |
+| **Models** | Model-agnostic. Tested with Qwen vLLM. Should work with Claude, GPT, or any opencode-supported provider. |
+| **Git** | Required (commit gate, baselines, rollback) |
+
+## Features
+
+- 🎯 **State-Machine Orchestration (SMO)** — awf guides the supervisor through phases: `init → goal → form → normalize → brief → run → verify → done`. Every tool returns a `next_action` hint — even weak models follow the full flow without getting lost.
+- 🔧 **29 MCP tools** — typed pipeline control: init, dispatch, start, approve, reject, rollback, dashboard, model validation. No bash, no manual file editing.
+- 📊 **Live Dashboard** — HTTP server with real-time polling. Chat-style agent handoffs, TODO content, TODO timeline, worker status, browser notifications. No page reloads.
+- 🧱 **Custom pipelines** — any roles, any depth. 1 stage or 10. You choose in the setup form.
+- ✅ **Approve / Reject** — symmetric verify tools. Approve commits and archives. Reject kills the pipeline and asks for fixes.
+- 🔍 **Pre-dispatch check** — before launching a pipeline, awf greps your codebase for keywords from the TODO. Warning if the task might already be done.
+- 🔄 **Crash recovery** — salvage path when workers don't signal, orphan TODO cleanup, state reconciliation on startup.
+- 📋 **Increment planning** — decomposition variants (vertical, horizontal, risk-first) presented as an HTML form for user choice.
+
+## Usage
+
+Talk in natural language — the supervisor agent calls the right tools:
+
+| You say | What happens |
+|---|---|
+| *"Initialize awf in my project"* | Creates `.agentic/`, detects stack, asks for your goal |
+| *"Develop the MVP"* | Opens setup form → configures pipeline → plans first TODO |
+| *"Verify"* | Supervisor reads handoffs, checks git diff, approves or rejects |
+| *"Reject — the cache is missing"* | Pipeline killed, new TODO dispatched with fix instructions |
+
+See [USAGE.md](USAGE.md) for full scenarios and tool reference.
+
+### SMO Flow
+
+```mermaid
+graph LR
+    init --> goal --> form --> normalize --> brief --> run --> verify --> done
+```
+
+| Phase | You do | Supervisor does |
+|---|---|---|
+| init | — | Creates `.agentic/`, detects stack |
+| goal | Answer "what do you want?" | Stores goal |
+| form | Fill setup form in browser | Opens form, recommends roles |
+| normalize | — | Analyzes role overlaps |
+| brief | — | Studies project, dispatches TODO |
+| run | Monitor dashboard | **IDLE** — waits for you |
+| verify | Say *"verify"* | Reviews, approves/rejects |
+| done | "continue" or "stop" | Waits for instruction |
+
+## Architecture
+
+```mermaid
+graph TD
+    A[opencode supervisor LLM] -->|MCP stdio - 29 tools| B[agent-workflow-ui plugin]
+    B -->|Python import| C[awf orchestrator]
+    C -->|subprocess| D[opencode run - worker agents]
+    C -->|HTTP daemon| E[Dashboard - live /api/state]
+```
+
+Two packages:
+- **`awf`** — Python core. Pipeline engine, phase state machine, signals, commit gate, dashboard server.
+- **`agent_workflow_ui`** — MCP plugin. Thin async wrappers + `next_action` guidance + HTML forms.
+
+## Comparison
+
+| | awf | Aider | Claude Code | Devin |
+|---|---|---|---|---|
+| Planning before code | ✅ | ❌ | ⚠️ | ✅ |
+| Human approve/reject | ✅ | ❌ | ❌ | ✅ |
+| Custom pipelines | ✅ | ❌ | ❌ | ❌ |
+| MCP-native | ✅ | ❌ | ❌ | ❌ |
+| Self-hosted / free | ✅ | ✅ | ❌ | ❌ |
+| Any LLM provider | ✅ | ✅ | ❌ | ❌ |
+
+## Dashboard
+
+Live HTTP dashboard opens automatically when pipeline starts:
+
+- **Two-panel layout** — pipeline sidebar (stages, progress, worker) + content tabs
+- **💬 Agent Chat** — handoffs as conversation messages with chain visualization
+- **📝 Задача** — full TODO content in rendered markdown
+- **📊 События** — meaningful events, newest first
+- **TODO timeline** — `[✅ TODO-0001] ─ [✅ TODO-0002] ─ [🔄 TODO-0003]`
+- **Browser notification** when pipeline reaches verify
+
+## Real-world results
+
+6 sessions on jira-epic-presenter (Qwen vLLM):
+- Full SMO flow end-to-end: init → goal → form → normalize → brief → run → verify
+- 4 TODOs per session, 1× approve (no loops), zero polling
+- Reject flow tested: supervisor found missing work, rejected, re-dispatched with fix
+- Pre-dispatch check caught already-implemented tasks
+
+## Roadmap
+
+- **SMO escape-hatch'и** — manual phase jumps, interruptions (from real session edge cases)
+- **Coverage** — critical paths (verify, plan_checkpoint, context)
+- **PyPI** — `pip install awf agent-workflow-ui` (no git clone needed)
+- **Dashboard v3** — stage timing bars, session summary, sound notifications
+- **Standalone mode** — awf without opencode (API-only)
+
+Full backlog: [BACKLOG.md](BACKLOG.md)
+
+## Documentation
+
+- [USAGE.md](USAGE.md) — usage scenarios and tool reference
+- [Architecture](vision/architecture.md) — components, data flow, design decisions
+- [Product Vision](vision/agent-ui-plugin.md) — competitive advantages
+- [Supervisor Flow (SMO)](vision/supervisor-flow.md) — phase system, next_action pattern
+- [CHANGELOG.md](CHANGELOG.md) — version history
+- [CONTRIBUTING.md](CONTRIBUTING.md) — how to contribute
+- [BACKLOG.md](BACKLOG.md) — open tasks
+- [README.ru.md](README.ru.md) — Russian README
+
+## License
+
+MIT — see [LICENSE](LICENSE).

awf-1.0.0/README.md

@@ -0,0 +1,159 @@
+# Agentic Workflow (awf)
+
+[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![tests](https://github.com/EnerJizeIT/agentic-workflow/actions/workflows/test.yml/badge.svg)](https://github.com/EnerJizeIT/agentic-workflow/actions/workflows/test.yml)
+
+> **Multi-agent pipeline orchestrator for opencode. Plan → build → verify → commit — through typed MCP tools, not bash.**
+
+## The problem it solves
+
+AI coding agents are powerful but chaotic. They jump straight to code without planning, skip review, leave bugs. You watch helplessly as tokens burn.
+
+**awf** adds structure: a supervisor agent plans the work, worker agents execute through a pipeline you design (any roles, any depth — from a single worker to a multi-stage chain), and you approve each result before it commits. All through natural language — *"start working on the backlog"*, *"verify and approve"*, *"reject — the DOMParser fix is missing"*.
+
+You stay in control. The agent stays on rails.
+
+## Quick Start
+
+```bash
+# 1. Install
+pip install -e .
+pip install -e ./agent_workflow_ui
+
+# 2. Configure opencode — add to ~/.config/opencode/opencode.json:
+# {
+#   "mcp": {
+#     "agent-workflow-ui": {
+#       "type": "local",
+#       "command": ["python3", "-m", "agent_workflow_ui"],
+#       "enabled": true
+#     }
+#   }
+# }
+
+# 3. Run — just talk to opencode:
+# "Initialize awf in my project"
+# "Develop the MVP based on the backlog"
+```
+
+## Requirements
+
+| Component | Requirement |
+|---|---|
+| **Python** | 3.10+ |
+| **opencode** | any recent version with MCP support |
+| **OS** | Linux (tested), macOS (should work), Windows (untested) |
+| **Models** | Model-agnostic. Tested with Qwen vLLM. Should work with Claude, GPT, or any opencode-supported provider. |
+| **Git** | Required (commit gate, baselines, rollback) |
+
+## Features
+
+- 🎯 **State-Machine Orchestration (SMO)** — awf guides the supervisor through phases: `init → goal → form → normalize → brief → run → verify → done`. Every tool returns a `next_action` hint — even weak models follow the full flow without getting lost.
+- 🔧 **29 MCP tools** — typed pipeline control: init, dispatch, start, approve, reject, rollback, dashboard, model validation. No bash, no manual file editing.
+- 📊 **Live Dashboard** — HTTP server with real-time polling. Chat-style agent handoffs, TODO content, TODO timeline, worker status, browser notifications. No page reloads.
+- 🧱 **Custom pipelines** — any roles, any depth. 1 stage or 10. You choose in the setup form.
+- ✅ **Approve / Reject** — symmetric verify tools. Approve commits and archives. Reject kills the pipeline and asks for fixes.
+- 🔍 **Pre-dispatch check** — before launching a pipeline, awf greps your codebase for keywords from the TODO. Warning if the task might already be done.
+- 🔄 **Crash recovery** — salvage path when workers don't signal, orphan TODO cleanup, state reconciliation on startup.
+- 📋 **Increment planning** — decomposition variants (vertical, horizontal, risk-first) presented as an HTML form for user choice.
+
+## Usage
+
+Talk in natural language — the supervisor agent calls the right tools:
+
+| You say | What happens |
+|---|---|
+| *"Initialize awf in my project"* | Creates `.agentic/`, detects stack, asks for your goal |
+| *"Develop the MVP"* | Opens setup form → configures pipeline → plans first TODO |
+| *"Verify"* | Supervisor reads handoffs, checks git diff, approves or rejects |
+| *"Reject — the cache is missing"* | Pipeline killed, new TODO dispatched with fix instructions |
+
+See [USAGE.md](USAGE.md) for full scenarios and tool reference.
+
+### SMO Flow
+
+```mermaid
+graph LR
+    init --> goal --> form --> normalize --> brief --> run --> verify --> done
+```
+
+| Phase | You do | Supervisor does |
+|---|---|---|
+| init | — | Creates `.agentic/`, detects stack |
+| goal | Answer "what do you want?" | Stores goal |
+| form | Fill setup form in browser | Opens form, recommends roles |
+| normalize | — | Analyzes role overlaps |
+| brief | — | Studies project, dispatches TODO |
+| run | Monitor dashboard | **IDLE** — waits for you |
+| verify | Say *"verify"* | Reviews, approves/rejects |
+| done | "continue" or "stop" | Waits for instruction |
+
+## Architecture
+
+```mermaid
+graph TD
+    A[opencode supervisor LLM] -->|MCP stdio - 29 tools| B[agent-workflow-ui plugin]
+    B -->|Python import| C[awf orchestrator]
+    C -->|subprocess| D[opencode run - worker agents]
+    C -->|HTTP daemon| E[Dashboard - live /api/state]
+```
+
+Two packages:
+- **`awf`** — Python core. Pipeline engine, phase state machine, signals, commit gate, dashboard server.
+- **`agent_workflow_ui`** — MCP plugin. Thin async wrappers + `next_action` guidance + HTML forms.
+
+## Comparison
+
+| | awf | Aider | Claude Code | Devin |
+|---|---|---|---|---|
+| Planning before code | ✅ | ❌ | ⚠️ | ✅ |
+| Human approve/reject | ✅ | ❌ | ❌ | ✅ |
+| Custom pipelines | ✅ | ❌ | ❌ | ❌ |
+| MCP-native | ✅ | ❌ | ❌ | ❌ |
+| Self-hosted / free | ✅ | ✅ | ❌ | ❌ |
+| Any LLM provider | ✅ | ✅ | ❌ | ❌ |
+
+## Dashboard
+
+Live HTTP dashboard opens automatically when pipeline starts:
+
+- **Two-panel layout** — pipeline sidebar (stages, progress, worker) + content tabs
+- **💬 Agent Chat** — handoffs as conversation messages with chain visualization
+- **📝 Задача** — full TODO content in rendered markdown
+- **📊 События** — meaningful events, newest first
+- **TODO timeline** — `[✅ TODO-0001] ─ [✅ TODO-0002] ─ [🔄 TODO-0003]`
+- **Browser notification** when pipeline reaches verify
+
+## Real-world results
+
+6 sessions on jira-epic-presenter (Qwen vLLM):
+- Full SMO flow end-to-end: init → goal → form → normalize → brief → run → verify
+- 4 TODOs per session, 1× approve (no loops), zero polling
+- Reject flow tested: supervisor found missing work, rejected, re-dispatched with fix
+- Pre-dispatch check caught already-implemented tasks
+
+## Roadmap
+
+- **SMO escape-hatch'и** — manual phase jumps, interruptions (from real session edge cases)
+- **Coverage** — critical paths (verify, plan_checkpoint, context)
+- **PyPI** — `pip install awf agent-workflow-ui` (no git clone needed)
+- **Dashboard v3** — stage timing bars, session summary, sound notifications
+- **Standalone mode** — awf without opencode (API-only)
+
+Full backlog: [BACKLOG.md](BACKLOG.md)
+
+## Documentation
+
+- [USAGE.md](USAGE.md) — usage scenarios and tool reference
+- [Architecture](vision/architecture.md) — components, data flow, design decisions
+- [Product Vision](vision/agent-ui-plugin.md) — competitive advantages
+- [Supervisor Flow (SMO)](vision/supervisor-flow.md) — phase system, next_action pattern
+- [CHANGELOG.md](CHANGELOG.md) — version history
+- [CONTRIBUTING.md](CONTRIBUTING.md) — how to contribute
+- [BACKLOG.md](BACKLOG.md) — open tasks
+- [README.ru.md](README.ru.md) — Russian README
+
+## License
+
+MIT — see [LICENSE](LICENSE).

awf-1.0.0/awf/__init__.py

@@ -0,0 +1,3 @@
+"""awf — Agentic Workflow Framework Python core."""
+
+__version__ = "0.4.0"

awf-1.0.0/awf/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for ``python3 -m awf``."""
+import sys
+
+from .cli import main
+
+sys.exit(main())

awf-1.0.0/awf/_atomic.py

@@ -0,0 +1,37 @@
+"""Atomic file write helpers for awf-core.
+
+Centralized so all modules use the same temp+rename pattern.
+"""
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def atomic_write_text(path: Path, content: str, encoding: str = "utf-8") -> None:
+    """Write text file atomically via temp + rename.
+
+    Creates parent dir if missing. Uses tempfile in same dir to guarantee
+    same-filesystem rename (atomic on POSIX).
+
+    H5 fix: plan_progress.py was direct write_text — crash mid-write
+    corrupted plan.md (the only persistent progress artifact).
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_path = tempfile.mkstemp(
+        prefix=f".{path.name}.",
+        suffix=".tmp",
+        dir=str(path.parent),
+    )
+    try:
+        with os.fdopen(fd, "w", encoding=encoding) as f:
+            f.write(content)
+        os.replace(tmp_path, path)
+    except Exception:
+        # Clean up temp file on failure
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise

awf-1.0.0/awf/_env.py

@@ -0,0 +1,90 @@
+"""BD-22/25: subprocess environment setup for opencode run.
+
+Centralized so signal_watch + supervisor + agent_stage can use it without
+circular imports through orchestrator.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+
+def _pdeathsig_preexec() -> None:
+    """DF6-8: Set PR_SET_PDEATHSIG so child dies when parent (orchestrator) dies.
+
+    Linux-only. On other platforms, no-op (best effort).
+    Prevents orphan worker subprocesses from continuing after orchestrator crash.
+    """
+    if sys.platform != "linux":
+        return
+    try:
+        import ctypes
+        import signal as _signal
+
+        libc = ctypes.CDLL("libc.so.6", use_errno=True)
+        PR_SET_PDEATHSIG = 1
+        libc.prctl(PR_SET_PDEATHSIG, _signal.SIGTERM)
+    except Exception:
+        pass  # best effort — don't crash if libc/prctl unavailable
+
+
+def awf_subprocess_env() -> dict[str, str]:
+    """BD-22/KAUD-5: env for opencode subprocess spawned by awf.
+
+    Sets ``OPENCODE_CONFIG_CONTENT`` to override permission rules so
+    the subprocess can run ``edit``/``bash``/``write`` without prompting.
+
+    KAUD-5: MERGES with user's existing opencode.json instead of replacing.
+    Reads user's config, adds our permission overrides on top, preserves
+    user's other settings (theme, providers, agents, etc.).
+
+    BD-25: strip ``OPENCODE_SERVER_*`` env vars so the subprocess does NOT
+    attach to a running ``opencode serve`` instance.
+    """
+    env = os.environ.copy()
+
+    # KAUD-5: Start from user's existing config, then merge our overrides
+    user_config: dict = {}
+    try:
+        from .xdg import opencode_config_file
+        config_path = opencode_config_file()
+        if config_path.is_file():
+            user_config = json.loads(config_path.read_text(encoding="utf-8"))
+            if not isinstance(user_config, dict):
+                user_config = {}
+    except (OSError, json.JSONDecodeError):
+        pass  # If user config is unreadable, start from empty
+
+    # Merge: user config + our permission overrides (ours take priority)
+    merged = user_config.copy()
+    merged_permissions = merged.get("permission", {})
+    if not isinstance(merged_permissions, dict):
+        merged_permissions = {}
+    merged_permissions.update({
+        "edit": "allow",
+        "bash": "allow",
+        "write": "allow",
+        "webfetch": "allow",
+    })
+    merged["permission"] = merged_permissions
+
+    # P1 security: only serialize permission overrides to env — never API keys,
+    # providers, or other sensitive fields from opencode.json. Workers only
+    # need the permission overrides; everything else is loaded by opencode
+    # itself from the real config file.
+    config_json = json.dumps({"permission": merged_permissions})
+    env["OPENCODE_CONFIG_CONTENT"] = config_json
+
+    # BD-25: strip server env vars
+    strip_keys = (
+        "OPENCODE_SERVER",
+        "OPENCODE_SERVER_URL",
+        "OPENCODE_SERVER_TOKEN",
+        "OPENCODE_HOST",
+        "OPENCODE_HOST_TOKEN",
+    )
+    for key in list(env.keys()):
+        if key in strip_keys:
+            env.pop(key, None)
+    return env

awf-1.0.0/awf/_log.py

@@ -0,0 +1,24 @@
+"""Lightweight file-based logger for awf.
+
+Centralized so any module can log without circular imports.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+from pathlib import Path
+
+
+def log(logs_dir: Path, message: str) -> None:
+    """Append a timestamped message to ``logs_dir/orchestrator.log``."""
+    if not logs_dir.exists():
+        try:
+            logs_dir.mkdir(parents=True, exist_ok=True)
+        except OSError:
+            return
+    log_file = logs_dir / "orchestrator.log"
+    ts = _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    try:
+        with open(log_file, "a", encoding="utf-8") as f:
+            f.write(f"[{ts}] {message}\n")
+    except OSError:
+        pass