workgraph 0.3.3__tar.gz

workgraph-0.3.3/LICENSE

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

workgraph-0.3.3/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: workgraph
+Version: 0.3.3
+Summary: Graph workflow orchestrator.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: termaid[rich]>=0.8.0
+Requires-Dist: tomlkit>=0.15.1
+Requires-Python: >=3.12
+Project-URL: Changelog, https://github.com/sylmarien/workgraph/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/sylmarien/workgraph
+Description-Content-Type: text/markdown
+
+# workgraph
+
+workgraph orchestrates development workflows declared as graphs. Nodes run
+agents or commands; a node's outcome selects the transition to follow. The
+developer writes the workflow once and starts a run from a harness session
+with `/workgraph`. The run prints one progress line per node. One command
+resumes a stopped run.
+
+The CLI bundles workflow and agent definitions; [Workflow
+files](docs/workflow-files.md) lists them. This repository runs the bundled
+`wg` workflow on itself:
+
+```mermaid
+flowchart TD
+    design([design])
+    design -->|done| approve-design
+    approve-design -->|accept| plan
+    approve-design -->|reject| design
+    plan -->|done| approve-plan
+    approve-plan -->|accept| implement
+    approve-plan -->|reject| plan
+    implement -->|done| test
+    test -->|pass| review
+    test -->|fail| implement
+    review --> code-review
+    review --> overengineering-review
+    review -->|pass| pr
+    review -->|fail| review-loop
+    review-loop -->|pass| implement
+    review-loop -->|fail| implement
+    review-loop -->|LIMIT| summary
+    summary -->|done| pr
+    pr -->|done| END
+```
+
+## Install
+
+As a Claude Code plugin:
+
+```
+/plugin marketplace add sylmarien/workgraph
+/plugin install workgraph@workgraph
+```
+
+Installing the plugin adds the `/workgraph` skill. The plugin's `install`
+skill installs the CLI with `uv`, and its `update` skill upgrades it. Both
+check that `uv` is on `PATH` and install nothing else.
+
+The CLI bundles workflow and agent definitions. A user's own definitions
+shadow them; see [Workflow files](docs/workflow-files.md) for the bundled
+definitions and the resolution order.
+
+As a Codex plugin:
+
+```sh
+codex plugin marketplace add sylmarien/workgraph
+codex plugin add workgraph@workgraph
+```
+
+Start a new Codex session and invoke `$workgraph <workflow> "#<issue>"`.
+The plugin shares the install, update, and run skills with the Claude Code
+plugin. The bundled workflows run nodes on the Claude harness, so they
+require `claude` and `uv` on `PATH` in Codex too.
+
+Codex reads the repository's existing marketplace at
+`.claude-plugin/marketplace.json` and its manifest at
+`.codex-plugin/plugin.json`. Both plugins ship in the same Git release.
+The patch, minor, and major release workflows update both manifests and
+the CLI to the same version. See the
+[Codex packaging documentation](https://developers.openai.com/plugins/build/plugins).
+
+Without the plugin:
+
+```sh
+uv tool install workgraph
+```
+
+`pip install workgraph` installs the same package from PyPI.
+`uv tool upgrade workgraph` upgrades it. Requires Python 3.12+. An agent
+node additionally requires the CLI of its harness on `PATH`: `claude` for
+`harness = "claude"`, `codex` for `harness = "codex"`.
+
+## Example
+
+```sh
+workgraph run wg "#12"
+```
+
+```
+design: done
+approve-design: parked
+parked at approve-design: Plan from this design? · spent 1m20s · $0.15
+Review material from design:
+https://github.com/sylmarien/workgraph/issues/12#issuecomment-5550441682
+```
+
+```sh
+workgraph resume --decision accept
+```
+
+```
+approve-design: accept
+plan: done
+approve-plan: parked
+parked at approve-plan: Implement this plan? · spent 4m05s · $0.42
+Review material from plan:
+<the plan>
+```
+
+`workgraph resume --decision accept` delivers the decision and resumes the
+run.
+
+## Reference
+
+- [Commands](docs/commands.md)
+- [Workflow files](docs/workflow-files.md)
+- [Agent definitions](docs/agent-definitions.md)
+
+## Development
+
+```sh
+uv sync
+uv run ruff check && uv run ruff format --check && uv run mypy && uv run pytest
+```
+
+The dogfood workflow runs the same gate: `workgraph run wg "#<issue>"`.

workgraph-0.3.3/README.md

@@ -0,0 +1,126 @@
+# workgraph
+
+workgraph orchestrates development workflows declared as graphs. Nodes run
+agents or commands; a node's outcome selects the transition to follow. The
+developer writes the workflow once and starts a run from a harness session
+with `/workgraph`. The run prints one progress line per node. One command
+resumes a stopped run.
+
+The CLI bundles workflow and agent definitions; [Workflow
+files](docs/workflow-files.md) lists them. This repository runs the bundled
+`wg` workflow on itself:
+
+```mermaid
+flowchart TD
+    design([design])
+    design -->|done| approve-design
+    approve-design -->|accept| plan
+    approve-design -->|reject| design
+    plan -->|done| approve-plan
+    approve-plan -->|accept| implement
+    approve-plan -->|reject| plan
+    implement -->|done| test
+    test -->|pass| review
+    test -->|fail| implement
+    review --> code-review
+    review --> overengineering-review
+    review -->|pass| pr
+    review -->|fail| review-loop
+    review-loop -->|pass| implement
+    review-loop -->|fail| implement
+    review-loop -->|LIMIT| summary
+    summary -->|done| pr
+    pr -->|done| END
+```
+
+## Install
+
+As a Claude Code plugin:
+
+```
+/plugin marketplace add sylmarien/workgraph
+/plugin install workgraph@workgraph
+```
+
+Installing the plugin adds the `/workgraph` skill. The plugin's `install`
+skill installs the CLI with `uv`, and its `update` skill upgrades it. Both
+check that `uv` is on `PATH` and install nothing else.
+
+The CLI bundles workflow and agent definitions. A user's own definitions
+shadow them; see [Workflow files](docs/workflow-files.md) for the bundled
+definitions and the resolution order.
+
+As a Codex plugin:
+
+```sh
+codex plugin marketplace add sylmarien/workgraph
+codex plugin add workgraph@workgraph
+```
+
+Start a new Codex session and invoke `$workgraph <workflow> "#<issue>"`.
+The plugin shares the install, update, and run skills with the Claude Code
+plugin. The bundled workflows run nodes on the Claude harness, so they
+require `claude` and `uv` on `PATH` in Codex too.
+
+Codex reads the repository's existing marketplace at
+`.claude-plugin/marketplace.json` and its manifest at
+`.codex-plugin/plugin.json`. Both plugins ship in the same Git release.
+The patch, minor, and major release workflows update both manifests and
+the CLI to the same version. See the
+[Codex packaging documentation](https://developers.openai.com/plugins/build/plugins).
+
+Without the plugin:
+
+```sh
+uv tool install workgraph
+```
+
+`pip install workgraph` installs the same package from PyPI.
+`uv tool upgrade workgraph` upgrades it. Requires Python 3.12+. An agent
+node additionally requires the CLI of its harness on `PATH`: `claude` for
+`harness = "claude"`, `codex` for `harness = "codex"`.
+
+## Example
+
+```sh
+workgraph run wg "#12"
+```
+
+```
+design: done
+approve-design: parked
+parked at approve-design: Plan from this design? · spent 1m20s · $0.15
+Review material from design:
+https://github.com/sylmarien/workgraph/issues/12#issuecomment-5550441682
+```
+
+```sh
+workgraph resume --decision accept
+```
+
+```
+approve-design: accept
+plan: done
+approve-plan: parked
+parked at approve-plan: Implement this plan? · spent 4m05s · $0.42
+Review material from plan:
+<the plan>
+```
+
+`workgraph resume --decision accept` delivers the decision and resumes the
+run.
+
+## Reference
+
+- [Commands](docs/commands.md)
+- [Workflow files](docs/workflow-files.md)
+- [Agent definitions](docs/agent-definitions.md)
+
+## Development
+
+```sh
+uv sync
+uv run ruff check && uv run ruff format --check && uv run mypy && uv run pytest
+```
+
+The dogfood workflow runs the same gate: `workgraph run wg "#<issue>"`.

workgraph-0.3.3/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "workgraph"
+version = "0.3.3"
+description = "Graph workflow orchestrator."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+    "termaid[rich]>=0.8.0",
+    "tomlkit>=0.15.1",
+]
+
+[project.urls]
+Repository = "https://github.com/sylmarien/workgraph"
+Changelog = "https://github.com/sylmarien/workgraph/blob/main/CHANGELOG.md"
+
+[project.scripts]
+workgraph = "workgraph.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.8.17,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.17",
+    "pytest>=8.4",
+    "pytest-cov>=6.2",
+    "python-semantic-release>=10.6.2",
+    "ruff>=0.12",
+]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+
+[tool.ruff.lint.pycodestyle]
+max-line-length = 120
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=workgraph --cov-report=term-missing"
+
+[tool.coverage.report]
+fail_under = 100
+
+[tool.semantic_release]
+commit_parser = "release_parser:AlwaysPatchCommitParser"
+version_toml = ["pyproject.toml:project.version"]
+version_variables = [".claude-plugin/plugin.json:version", ".codex-plugin/plugin.json:version"]
+allow_zero_version = true

workgraph-0.3.3/src/workgraph/__init__.py

@@ -0,0 +1 @@
+"""Graph workflow orchestrator."""

workgraph-0.3.3/src/workgraph/claude.py

@@ -0,0 +1,106 @@
+"""The Claude Code harness: argv, result reading, and transcript rendering."""
+
+import json
+import textwrap
+from collections.abc import Iterator, Sequence
+from contextlib import contextmanager
+from typing import Any
+
+from rich.text import Text
+
+from workgraph.harness import (
+    AgentInvocation,
+    NodeFailure,
+    iter_jsonl_events,
+    read_last_value,
+    split_lines,
+)
+
+
+@contextmanager
+def build_argv(invocation: AgentInvocation) -> Iterator[list[str]]:
+    """Yield the argv that runs the agent through the Claude Code CLI."""
+    agent_definition = invocation.agent_definition
+    agents = {
+        invocation.agent_name: {
+            "description": agent_definition.get("description", ""),
+            "prompt": agent_definition["prompt"],
+        }
+    }
+    # No --bare: bare mode reads no OAuth credentials, so agent nodes cannot
+    # authenticate for subscription users. Accepted cost: hooks and plugins
+    # load on every spawn.
+    argv = [
+        "claude",
+        "-p",
+        invocation.prompt,
+        "--output-format",
+        "stream-json",
+        "--verbose",
+        "--json-schema",
+        json.dumps(invocation.outcome_schema),
+        "--agents",
+        json.dumps(agents),
+        "--agent",
+        invocation.agent_name,
+        "--permission-mode",
+        "dontAsk",
+        "--model",
+        invocation.model,
+        "--effort",
+        invocation.effort,
+    ]
+    allowed_tools = agent_definition.get("tools", invocation.allowed_tools)
+    if allowed_tools is not None:
+        argv += ["--allowedTools", allowed_tools]
+    if invocation.session is not None:
+        # The node run continues the session in place.
+        argv += ["--resume", invocation.session]
+    yield argv
+
+
+def read_result(invocation: AgentInvocation, stdout_lines: Sequence[str]) -> tuple[Any, float]:
+    """Return the structured output of the last result event and the cost it reports."""
+    agent_node_name = invocation.agent_node_name
+    result_events = [
+        event for event in iter_jsonl_events(stdout_lines) if event.get("type") == "result"
+    ]
+    if not result_events:
+        raise NodeFailure(f"node '{agent_node_name}': agent output holds no result event")
+    result_event = result_events[-1]
+    try:
+        cost = float(result_event.get("total_cost_usd") or 0)
+    except (TypeError, ValueError):
+        # A malformed cost counts as zero; the run continues.
+        cost = 0.0
+    if result_event.get("is_error"):
+        raise NodeFailure(f"node '{agent_node_name}': agent reported an error", cost)
+    return result_event.get("structured_output"), cost
+
+
+def read_session(stdout_lines: Sequence[str]) -> str | None:
+    """Return the session id of the last stream event that carries one."""
+    return read_last_value(iter_jsonl_events(stdout_lines), "session_id")
+
+
+def render_transcript(stdout_lines: Sequence[str]) -> list[Text]:
+    """Render the text blocks and tool calls of stream-json lines. Drop every other line."""
+    transcript_rows: list[Text] = []
+    for stream_event in iter_jsonl_events(stdout_lines):
+        if stream_event.get("type") != "assistant":
+            continue
+        for block in stream_event["message"]["content"]:
+            if block["type"] == "text":
+                transcript_rows += split_lines(block["text"])
+            elif block["type"] == "tool_use" and block["name"] != "StructuredOutput":
+                transcript_rows.append(
+                    Text(f"▸ {block['name']}: {_summarize_tool_input(block['input'])}", "bold")
+                )
+    return transcript_rows
+
+
+def _summarize_tool_input(tool_input: dict[str, Any]) -> str:
+    for key in ("command", "file_path", "pattern", "url"):
+        if key in tool_input:
+            return str(tool_input[key])
+    return textwrap.shorten(json.dumps(tool_input), 100, placeholder="...")