ww-agentic-workflows 1.0.0.dev3__tar.gz

ww_agentic_workflows-1.0.0.dev3/.claude/settings.json

@@ -0,0 +1,48 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/ww hook session-start --agent claudecode",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/ww hook stop --agent claudecode",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/ww hook stop --agent claudecode",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/ww hook interrupt --agent claudecode",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

ww_agentic_workflows-1.0.0.dev3/.claude/skills/noww/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: noww
+description: Work without ww. Use only when the user invokes /noww or asks not to use ww.
+---
+
+# Work without ww
+
+Do not use ww for the rest of this conversation, unless the user asks for it
+again: do not run `./ww discover`, and do not start, continue, or complete a ww
+task, `catchall` included. Carry out requests directly, as in a project without
+ww. A ww task already in progress stays as it is; do not reset or fail it.

ww_agentic_workflows-1.0.0.dev3/.claude/skills/update-architecture-documentation/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: update-architecture-documentation
+description: Updates the documentation/architecture.md file with the recent changes to the architecture of this application.
+---
+
+# Update architecture documentation
+
+Use this skill to update the documentation of the architecture of this application. 
+Whenever explicitly asked, or if changes to the code are meaningful enough to be considered as architecture changes, keep the documentation up-to-date.
+
+The location of the documentation is documentation/architecture.md.
+
+The goal of that documentation is to serve an always up-to-date reference for developers/humans, and for LLM agents as well, when developing new features, or reviewing the code.
+
+## Constraints
+
+- Keep the documentation more high-level than deeply describing the code.
+- Keeping the references to files/functions is acceptable.
+- Concentrate on the "why" question more, rather than on "how" and "what" (although it is also important).

ww_agentic_workflows-1.0.0.dev3/.claude/skills/ww/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: ww
+description: Carry out a development request through ww, this project's workflow tool. Use only when the request changes something (implement, fix, refactor, merge, edit documentation) or the user explicitly asks to work via ww, to start or continue a ww task, or to run a ww workflow; where `./ww discover` says ww is used by default, use it before changing files for any request, since every change then goes through ww. Never use it for reviews, questions, explanations, investigations, status checks or other read-only work, even when they concern ww or a ww task.
+---
+
+# Work through ww
+
+ww is for development: requests that change files. A review, question,
+explanation, investigation, status check or other read-only request never
+goes through ww; answer it directly, without these steps and without a task,
+even where ww is used by default. When a read-only conversation turns into a
+change, start from step 1 then.
+
+1. Run `./ww discover` and read all of it. If it says ww is disabled, stop:
+   do not use ww, and tell the user. If it says ww is used only on request
+   and the user did not explicitly ask for ww (invoking this skill counts),
+   carry out the request without ww and do not ask.
+2. To continue an existing task, run
+   `./ww instruction <task-id> --role manager` instead of starting a new one.
+3. Otherwise choose the workflow that matches the request, keep its default
+   modes unless the user's wording matches another mode, and start the task
+   with the start command `discover` shows. Pass the user's requirements,
+   normalized, as `--requirements`. When the request names an external
+   ticket, such as a Jira key, use that key as the task ID; omit the ID only
+   when there is none or the workflow obtains its own.
+   When no workflow fits and you are about to change files, do not start
+   `catchall` directly: run `./ww lookup [<task>] --agent <agent>` with the
+   task the conversation works on or the request names, as written, and
+   follow its answer, then do the work as you would without ww. Read-only work
+   needs no task.
+   When the first page of `start` says rules have no check
+   yet, tell the user once and carry on: it never blocks the task, and the
+   `ww-scriptize` skill builds those checks when they want it.
+4. Follow every ww response exactly: run each displayed command with all
+   placeholders replaced, and keep going until ww reports that the workflow
+   is complete or reports an error. On `interactive: true` steps, converse
+   naturally until intent to finish is clear, ask if ambiguous, and treat
+   "done for today" as a pause. Record and end the interaction before
+   completing it. Use the host choice tool when available; keep asynchronous
+   choices pending until an answer arrives, and do not treat timeouts or
+   preselection as answers. After completion, relay any optional
+   `ww-deduce-feedback` suggestion; do not insert learning into the plan.
+   Deduction uses ww commands and explicit existing point IDs; rule review
+   and pruning are separate, and rules require operator approval.
+5. Never run a ww-owned handler yourself, edit ww state, or read
+   `ww.yaml` or ww's source to work out what to do next. For a handler repair
+   assignment, fix the cause and complete with an artifact; ww retries the
+   command. In `auto`, the manager dispatches the repair with `next`. When
+   ww reports `awaiting_operator` (a failed handler or work, an interrupted
+   command, a loop at its iteration limit, a changed workflow), stop and report the task, its
+   `operator_reason` and the exact error to the user (unless they gave a
+   standing authorization for routine repairs such as dependency installation,
+   formatting or retries: apply it to a stop of that kind without asking again,
+   and ask only for a material decision or an action outside it); when they
+   decide, run the recovery command ww showed, `./ww next <task-id> --retry` to run the
+   handler again, `--force --reason` to skip it or leave the loop, or
+   `--replan` / `--keep-plan` for a changed workflow. A `pass_incomplete`
+   stop is cleared by recording what it names with `./ww update-item`, then
+   `./ww next <task-id> --retry`; `--force` is refused there.

ww_agentic_workflows-1.0.0.dev3/.codex/hooks.json

@@ -0,0 +1,59 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\"/ww hook session-start --agent codex",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\"/ww hook stop --agent codex",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\"/ww hook stop --agent codex",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Interrupt": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\"/ww hook interrupt --agent codex",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\"/ww hook interrupt --agent codex",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

ww_agentic_workflows-1.0.0.dev3/.codex/skills/noww/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: noww
+description: Work without ww. Use only when the user invokes /noww or asks not to use ww.
+---
+
+# Work without ww
+
+Do not use ww for the rest of this conversation, unless the user asks for it
+again: do not run `./ww discover`, and do not start, continue, or complete a ww
+task, `catchall` included. Carry out requests directly, as in a project without
+ww. A ww task already in progress stays as it is; do not reset or fail it.

ww_agentic_workflows-1.0.0.dev3/.codex/skills/update-architecture-documentation/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: update-architecture-documentation
+description: Updates the documentation/architecture.md file with the recent changes to the architecture of this application.
+---
+
+# Update architecture documentation
+
+Use this skill to update the documentation of the architecture of this application. 
+Whenever explicitly asked, or if changes to the code are meaningful enough to be considered as architecture changes, keep the documentation up-to-date.
+
+The location of the documentation is documentation/architecture.md.
+
+The goal of that documentation is to serve an always up-to-date reference for developers/humans, and for LLM agents as well, when developing new features, or reviewing the code.
+
+## Constraints
+
+- Keep the documentation more high-level than deeply describing the code.
+- Keeping the references to files/functions is acceptable.
+- Concentrate on the "why" question more, rather than on "how" and "what" (although it is also important).

ww_agentic_workflows-1.0.0.dev3/.codex/skills/ww/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: ww
+description: Carry out the user's request through ww, this project's workflow tool. Use when the user asks to work via ww, to start or continue a ww task, or to run a ww workflow, and, where `./ww discover` says ww is used by default, before changing files for any request, since every change then goes through ww. Not for questions or other read-only work.
+---
+
+# Work through ww
+
+1. Run `./ww discover` and read all of it. If it says ww is disabled, stop:
+   do not use ww, and tell the user. If it says ww is used only on request
+   and the user did not explicitly ask for ww (invoking this skill counts),
+   carry out the request without ww and do not ask.
+2. To continue an existing task, run
+   `./ww instruction <task-id> --role manager` instead of starting a new one.
+3. Otherwise choose the workflow that matches the request, keep its default
+   modes unless the user's wording matches another mode, and start the task
+   with the start command `discover` shows. Pass the user's requirements,
+   normalized, as `--requirements`. When the request names an external
+   ticket, such as a Jira key, use that key as the task ID; omit the ID only
+   when there is none or the workflow obtains its own.
+   When no workflow fits and you are about to change files, do not start
+   `catchall` directly: run `./ww lookup [<task>] --agent <agent>` with the
+   task the conversation works on or the request names, as written, and
+   follow its answer, then do the work as you would without ww. Questions and
+   other read-only work need no task.
+4. Follow every ww response exactly: run each displayed command with all
+   placeholders replaced, and keep going until ww reports that the workflow
+   is complete or reports an error.
+5. Never run a ww-owned handler yourself, edit ww state, or read
+   `ww.yaml` or ww's source to work out what to do next. When
+   ww reports `awaiting_operator` (a failed handler or work, an interrupted
+   command, a loop at its iteration limit), stop and report the task, its
+   `operator_reason` and the exact error to the user; when they decide, run
+   the recovery command ww showed, `./ww next <task-id> --retry` to run the
+   handler again or `--force --reason` to skip it or leave the loop.

ww_agentic_workflows-1.0.0.dev3/.git-blame-ignore-revs

@@ -0,0 +1,2 @@
+# The commit that applied ruff format to the whole codebase.
+d13f27b8c8e7dac378b3da0660996f8087f18a12

ww_agentic_workflows-1.0.0.dev3/.githooks/pre-commit

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+# Add SPDX identifiers to staged Python and shell files before committing.
+exec python3 scripts/ensure_spdx_license.py --staged

ww_agentic_workflows-1.0.0.dev3/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,84 @@
+name: Bug report
+description: Something in ww behaved differently from what its documentation says.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting. ww is in beta, so this is genuinely useful.
+
+        **Before you paste:** `.ww/`, command output, and task state can contain
+        credentials or other private values. Sanitise anything you copy in. See
+        [Sensitive runtime data](https://github.com/from-developers-for-developers/agentic-workflows#sensitive-runtime-data).
+
+        Check [limitations.md](https://github.com/from-developers-for-developers/agentic-workflows/blob/main/documentation/limitations.md)
+        first — it lists what ww deliberately does not do yet.
+
+  - type: textarea
+    id: workflow
+    attributes:
+      label: The workflow
+      description: >
+        The relevant part of your `ww.yaml`, reduced to what still
+        reproduces the problem.
+      render: yaml
+    validations:
+      required: true
+
+  - type: textarea
+    id: command
+    attributes:
+      label: The command and its output
+      description: >
+        The exact command you ran, its exit code, and the exact message ww
+        printed. Sanitise it first.
+      render: console
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected instead
+    validations:
+      required: true
+
+  - type: textarea
+    id: agent_account
+    attributes:
+      label: Your agent's own account of what went wrong
+      description: >
+        If you hit this while working through an agent, ask it to summarise
+        what it ran, what ww told it, and where it got stuck, and paste that
+        here. It is often the fastest route to the real cause. Leave blank if
+        you ran ww by hand.
+    validations:
+      required: false
+
+  - type: input
+    id: version
+    attributes:
+      label: ww version
+      description: Output of `ww-agentic-workflows --version`, plus the commit you are on.
+      placeholder: "0.1.0 (main @ 28e55aa)"
+    validations:
+      required: true
+
+  - type: input
+    id: environment
+    attributes:
+      label: OS, Python version, and agent
+      placeholder: "macOS 15.5, Python 3.12.14, Claude Code"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: runtime
+    attributes:
+      label: Runtime
+      options:
+        - single
+        - auto
+        - not applicable
+    validations:
+      required: true

ww_agentic_workflows-1.0.0.dev3/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/from-developers-for-developers/agentic-workflows/security/advisories/new
+    about: Report privately through a security advisory, never as a public issue.
+  - name: Documentation
+    url: https://github.com/from-developers-for-developers/agentic-workflows/tree/main/documentation
+    about: Specification, features, examples, architecture, and known limitations.

ww_agentic_workflows-1.0.0.dev3/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,38 @@
+name: Feature request
+description: Suggest a capability or a change to how ww behaves.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please check
+        [limitations.md](https://github.com/from-developers-for-developers/agentic-workflows/blob/main/documentation/limitations.md)
+        first — some gaps are deliberate, and it says which.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: >
+        What process are you trying to express, and where does ww get in the
+        way today? Describe the workflow, not only the missing feature.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you would like instead
+      description: >
+        If it affects `ww.yaml`, sketch the YAML you would want to
+        write.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What you tried or considered
+      description: Existing hooks, handlers, items, loops, or an extension.
+    validations:
+      required: false

ww_agentic_workflows-1.0.0.dev3/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,23 @@
+## What this changes
+
+<!-- The behaviour that differs afterwards, in a sentence or two. -->
+
+## Why
+
+<!-- The problem it solves. Link the issue if there is one. -->
+
+## How it was verified
+
+<!-- The checks you ran, and anything you exercised by hand. -->
+
+- [ ] `.venv/bin/python -m pytest`
+- [ ] `.venv/bin/python -m ruff check src tests scripts` and `ext/ww/git`
+- [ ] `.venv/bin/python -m mypy`
+- [ ] `.venv/bin/python scripts/check_release_gates.py` (release-facing changes)
+- [ ] `.venv/bin/python scripts/check_distribution.py` (release-facing changes)
+
+## Checklist
+
+- [ ] `CHANGELOG.md` updated under today's date, if the change is user-visible.
+- [ ] Documentation under `documentation/` updated, if behaviour or `ww.yaml` changed.
+- [ ] Persisted-format changes carry a schema bump and are called out as incompatible.

ww_agentic_workflows-1.0.0.dev3/.github/workflows/dev-publish.yml

@@ -0,0 +1,56 @@
+name: Publish development snapshot
+
+on:
+  push:
+    branches: [dev]
+
+permissions:
+  contents: read
+
+jobs:
+  gates:
+    uses: ./.github/workflows/release-gates.yml
+
+  build:
+    needs: gates
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+      - name: Stamp the upcoming release's development version
+        run: python scripts/set_dev_version.py --base-version 1.0.0 --run-number "$GITHUB_RUN_NUMBER"
+      # The distribution check imports ww from the checkout, so it needs the
+      # runtime dependencies as well as the build tools.
+      - run: python -m pip install build twine .
+      - run: python -m build
+      - run: python -m twine check --strict dist/*
+      - run: python scripts/check_distribution.py --dist-dir dist
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: dev-distributions
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 7
+          overwrite: true
+
+  publish:
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
+    runs-on: ubuntu-latest
+    environment: pypi-dev
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: dev-distributions
+          path: dist
+      - name: Publish the validated distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          # A rerun keeps the version and can finish a partially uploaded release.
+          skip-existing: true

ww_agentic_workflows-1.0.0.dev3/.github/workflows/release-gates.yml

@@ -0,0 +1,43 @@
+name: Release gates
+
+on:
+  workflow_call:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  quality-and-compatibility:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Keep the declared minimum executable, alongside the primary CI runtime.
+        python-version: ["3.10", "3.12"]
+    steps:
+      # Pinned to commits, not tags: a tag can be repointed at new code.
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install -e '.[dev]'
+      - run: python -m ruff format --check src tests scripts ext/ww/git
+      - run: python -m ruff check src tests scripts ext/ww/git
+      - run: python -m mypy
+      - run: python scripts/check_release_gates.py
+      - run: python -m pytest
+      # Build, inspect, and install artifacts without the source checkout on sys.path.
+      - run: python scripts/check_distribution.py
+      # One runtime dependency and a few dev tools, but the answer to
+      # "is any of it known-vulnerable?" should be checked every run, not when
+      # someone thinks to ask. The set is frozen before pip-audit is installed
+      # so the auditor's own dependencies are not audited too, and without the
+      # editable project, which has no release to compare against and which
+      # --strict would otherwise treat as a collection failure.
+      - name: Audit dependencies for known vulnerabilities
+        if: matrix.python-version == '3.12'
+        run: |
+          python -m pip freeze --exclude-editable > "$RUNNER_TEMP/audit-requirements.txt"
+          python -m pip install pip-audit
+          pip-audit --strict -r "$RUNNER_TEMP/audit-requirements.txt"

ww_agentic_workflows-1.0.0.dev3/.gitignore

@@ -0,0 +1,19 @@
+.ww/*
+!.ww/project.md
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+.venv/
+/ww
+.idea
+/tasks
+/.codex/config.toml
+/ww-worktrees
+.env
+*ww.local.yaml
+*ww.local.json
+ww-setup.local.yaml
+
+# Planning notes stay local
+/documentation/plans/

ww_agentic_workflows-1.0.0.dev3/AGENTS.md

@@ -0,0 +1,11 @@
+## Codex execution boundary
+
+Run WW CLI commands using Codex's normal sandbox policy. Do not request
+escalation preemptively.
+
+If a specific WW command fails because sandbox access prevents it from
+completing, rerun only that command outside the sandbox with approval. WW
+remains the trusted execution boundary for its handlers; do not invoke its Git
+or other handlers separately.
+
+@WW_AGENT_INSTRUCTIONS.md