from-developers-for-developers/agentic-workflows

Contribute to from-developers-for-developers/agentic-workflows development by creating an account on GitHub.

Summary

ww-agentic-workflows is a Python CLI (ww) that compiles a workflows.yaml file into an explicit, resumable plan for coding agents, separating agent-performed work from automation that ww itself runs. It is local-first, GPL-3.0-or-later, and currently in beta with no PyPI release — installation is an editable pipx install from a git clone.

What it is useful for

The tool fits development processes that need more structure than a single prompt: multi-step tasks with lifecycle hooks, reusable CLI handlers (tests, linters, commits) that ww executes around agent work, MCP-backed actions such as a Jira step, and durable per-task state under .ww/ so work can be inspected, handed off, or resumed by a different agent. The bundled ww/git extension and a per-project agentic-workflows.json let one instance coordinate multiple repositories, with base branches that can be literal names or shell-free commands returning one line on stdout. Documented runtimes are single (one session does everything) and auto (the manager delegates each assignment to a selected worker).

How engineers can use it

The README requires Python 3.10+ and pipx, then:

mkdir -p ~/tools
git clone https://github.com/from-developers-for-developers/agentic-workflows.git ~/tools/agentic-workflows
pipx install --editable ~/tools/agentic-workflows

From the project root, ww-agentic-workflows init scaffolds workflows.yaml, an ./ww launcher, WW_AGENT_INSTRUCTIONS.md, and agentic-workflows.json; in a Git repo it can enable ww/git and add .ww/ to .gitignore. A minimal workflow:

workflows:
  - name: task
    steps:
      - develop: Implement the requested change.
      - test: Run the tests and fix what fails.
      - document: Update the documentation the change affects.

Validate with ww-agentic-workflows lint and preview the compiled plan with ww-agentic-workflows plan --workflow task --agent claudecode. The agent — supported integrations are codex, claudecode, gemini, antigravity, deepseek, kimi, cursor, grok, or custom:<name> — starts the task with ww-agentic-workflows start, then drives next and complete per step; handlers run inside those calls, so the agent does not execute them. Monitor with ww-agentic-workflows status TASK-123, artifacts TASK-123, and instruction TASK-123 --role manager; the instruction command is what a new session reads to resume.

Documented limitations to plan around: native Windows is unsupported (use WSL); .ww/ task state is versioned and an unfinished task may refuse to load after an upgrade, so in-flight tasks should be finished or reset before pulling; CLI output is not a stable machine interface, so scripts should use --json; there are no tagged releases, so pin by commit if you need a fixed target; the CLI periodically runs git fetch against the remote you cloned from and prints an update notice, disableable per project with "update_check": false or globally with WW_UPDATE_CHECK=0. Using ww against another project does not, by itself, impose GPL on that project's code or configuration.