ww-agentic-workflows 1.0.0.dev3__py3-none-any.whl

ww/assets/ww-wizard_skill.md

@@ -0,0 +1,105 @@
+---
+name: ww-wizard
+description: Help the operator create a ww workflow, change an existing one, create or improve rules, or choose an approach, adapting the questions to the request and placing every change through ww's own commands. Use when the operator invokes /ww-wizard, or asks to design, change or tune how ww works in this project and has not said exactly what to edit.
+---
+
+# Shape ww's setup with the operator
+
+Talk in plain words and ask only what changes the outcome. This skill
+orchestrates: ww's design documents decide what a setup can be made of, ww's
+commands validate and place every change, and the rules skills write rules.
+Never edit ww's configuration files yourself.
+
+## Start
+
+1. Run `./ww discover`. If ww is disabled, say so and stop. Read the
+   operator's request.
+2. If it already says what to do, go straight to that branch. Otherwise ask
+   which one, as a single choice through the host's choice tool where
+   available (a numbered list in the chat otherwise), and end your turn until
+   the operator answers:
+   - Create a workflow.
+   - Change an existing workflow.
+   - Create or improve rules.
+   - Help me choose an approach.
+3. Match the depth of your questions to the request: a precise request gets
+   one confirming question at most; a vague one gets the few questions it
+   needs, one message at a time. A timeout or a preselected value is not an
+   answer.
+
+Before drafting anything, read the design authorities the branch needs, which
+every installation prints: `./ww docs features` (start at "Designing a
+workflow"), `./ww docs specification` for exact syntax and `./ww docs
+examples` for the shape of a setup. Inspect the project: `.ww/project.md` when
+it exists, the project's own commands and CI, and the workflows already
+configured. Take a test, lint or type command only from that evidence and say
+where it comes from; where it is missing or contradictory, ask instead of
+guessing.
+
+## Create a workflow
+
+Ask for the trigger, the result wanted and where the operator wants to be
+involved. Choose the smallest structure that expresses it, adding items,
+loops, assessments, modes or reusable groups only for a concrete requirement
+the features guide gives a reason for. Challenge anything the request does not
+need: name a simpler alternative and what it costs the operator, and let them
+decide; do not walk through every property. Then show concise YAML and a short
+walkthrough of a representative task, with a failure and retry path when an
+external effect or an automatic command is involved. Write the draft as a
+setup fragment (root keys `workflows`, `modes`, `documents`, `handlers`,
+`hooks`, `rules`, plus `settings`) to a file outside the repository, such as in
+your scratch directory.
+
+## Change an existing workflow
+
+1. Find where it is defined: `./ww discover --json` gives each workflow's
+   `source` file and `source_level` (`local`, `project` or `global`). State
+   which definition is in force and which level it is at.
+2. Draft the complete changed workflow as a fragment whose `workflows` list
+   holds that one entry. Keep what the operator did not ask to change.
+3. Edit it where it is written: `./ww setup update <name> <fragment>`, adding
+   `--level <source_level>` so that ww refuses rather than edit a definition
+   another level hides. If the operator wants a change for themselves only to a
+   shared workflow, say that this is an override that hides the shared
+   definition for them alone, and place it with `./ww setup apply <fragment>
+   --for me` only when they confirm. Never create such an override silently,
+   and never hide a shared edit under a local one.
+4. A workflow ww ships (`catchall`, the `ww-*` ones) is not edited: a same-named
+   definition placed with `setup apply` replaces it.
+
+## Create or improve rules
+
+Hand the work to the rules skills instead of writing rules yourself: `ww-rule`
+for rules in the operator's own words, `ww-rules-from-artifacts` for lessons
+that recur in past results, `ww-feedback-rules` for learned operator feedback,
+and `ww-scriptize` to give rules that have none a check. Say which one fits and
+why, then follow it.
+
+## Help me choose an approach
+
+Ask what goes wrong or what the operator wants to be easier, then lay out two
+or three options in plain words, each with what it asks of the operator and
+what it costs: a rule, a check, a mode, a small workflow, or doing nothing.
+Recommend the simplest that meets the need. When they pick one, continue in its
+branch.
+
+## Validate, show, apply
+
+1. Validate and inspect the draft before asking anything:
+   `./ww setup apply <fragment> --for <me or team> --dry-run --inspect <workflow>
+   --agent <your agent>` for new definitions, `./ww setup update <name>
+   <fragment> --dry-run --inspect <workflow> --agent <your agent>` for a
+   change. In the compiled plan, check that automation is ww-owned (commands
+   run as handlers or hooks, never as a step asking the agent to run them),
+   that item scopes are valid, and that the operator meets only the
+   conversations they intended. Fix the draft and validate again until it is
+   clean.
+2. Show the YAML or the diff, the walkthrough, and the dry run's list of
+   changes. For a new definition, ask whether it is for the operator alone
+   (`--for me`, local files kept out of version control) or the team
+   (`--for team`, shared files).
+3. When the operator approves the shown edit, apply exactly it with `--yes`;
+   do not ask again. If ww refuses, show its message and stop; never place the
+   configuration another way.
+4. Run `./ww lint`, tell the operator which files changed, and that shared
+   ones are left uncommitted for them to review and commit.

ww/assets/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/assignments.py

@@ -0,0 +1,283 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Structural worker-assignment boundaries for compiled workflow plans."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ww.control import is_coordinator, workflow_transition
+from ww.errors import StateError
+from ww.plan import PlanItem, WorkflowPlan
+from ww.workflow_config import ProvidedVariable
+
+
+@dataclass(frozen=True)
+class Assignment:
+    """One manager-dispatched unit of agent and automatic lifecycle work."""
+
+    first_item_id: str
+    start: int
+    stop: int
+
+
+def selection_item(plan: WorkflowPlan, assignment: Assignment) -> PlanItem | None:
+    """Return the item whose request drives a worker selection.
+
+    The main step wins; in a hook-only assignment an agent-owned hook wins
+    over a handler that merely waits for values, because the worker is
+    shaped for the work it performs, not for the value it types in.
+    """
+    items = plan.items[assignment.start : assignment.stop]
+    for choose in (
+        lambda item: item.phase == "step" and item.owner == "agent",
+        lambda item: item.owner == "agent",
+        lambda item: item.requires_agent_input,
+    ):
+        found = next((item for item in items if choose(item)), None)
+        if found is not None:
+            return found
+    return None
+
+
+def assignment_at(
+    plan: WorkflowPlan, cursor: int, *, runtime: str
+) -> Assignment | None:
+    """Return the assignment beginning at ``cursor``, if it is worker-owned.
+
+    Preparation hooks share an assignment with the main action at the same
+    structural step. Completion hooks on ancestors trail the final descendant.
+    A new preparation/main action, item expansion, child coordinator, workflow
+    transition, or unrelated completion lifecycle ends the assignment. The
+    built-in workflow summary is deliberately included in the final assignment.
+
+    In the ``auto`` runtime, an ``items`` step with ``item_assignment`` set to
+    ``per_item`` or ``together`` keeps later stages of the same item, or of
+    every item, in the assignment, and a ``loop`` with ``loop_assignment``
+    ``per_round`` keeps the following body steps of the same round while
+    they resolve to the same worker settings.  The ``single`` runtime keeps
+    per-step boundaries because one session already performs every assignment.
+
+    A verification item is an assignment of its own, so the worker who did a
+    step never verifies it.
+    """
+    if cursor >= len(plan.items):
+        return None
+    first = plan.items[cursor]
+    if _coordinator(first):
+        return None
+    if first.verifies is not None:
+        return Assignment(first.id, cursor, cursor + 1)
+    spans_steps = runtime != "single"
+    lineage = {first.step, *first.ancestors}
+    worker = first if first.owner == "agent" else None
+    stop = cursor + 1
+    while stop < len(plan.items):
+        item = plan.items[stop]
+        if _coordinator(item) or item.verifies is not None:
+            break
+        if item.summary:
+            stop += 1
+            continue
+        if item.phase in {"before_start_workflow", "before_start", "step"}:
+            if item.step != first.step:
+                if not spans_steps or not (
+                    shares_item_span(first, item, worker=worker)
+                    or shares_loop_span(first, item, worker=worker)
+                ):
+                    break
+                lineage.update((item.step, *item.ancestors))
+            if worker is None and item.owner == "agent":
+                worker = item
+            stop += 1
+            continue
+        if item.step not in lineage:
+            break
+        stop += 1
+    return Assignment(first.id, cursor, stop)
+
+
+def shares_item_span(
+    first: PlanItem, item: PlanItem, *, worker: PlanItem | None
+) -> bool:
+    """Whether ``item`` continues the per-item assignment begun at ``first``."""
+    if first.item_id is None or item.item_id is None:
+        return False
+    if first.item_pass != item.item_pass:
+        return False
+    if first.item_assignment != item.item_assignment:
+        return False
+    if item.item_assignment == "per_item" and first.item_id != item.item_id:
+        return False
+    if item.item_assignment == "per_step":
+        return False
+    return _same_worker(item, worker)
+
+
+def shares_loop_span(
+    first: PlanItem, item: PlanItem, *, worker: PlanItem | None
+) -> bool:
+    """Whether ``item`` continues the loop round begun at ``first``."""
+    if first.loop_id is None or first.loop_id != item.loop_id:
+        return False
+    if item.loop_assignment != "per_round":
+        return False
+    return _same_worker(item, worker)
+
+
+def _same_worker(item: PlanItem, worker: PlanItem | None) -> bool:
+    """Whether ``item`` can be performed by the assignment's current worker.
+
+    ``worker`` is the first agent-owned item of the assignment so far. A step
+    that needs a different agent, model, reasoning, or profile, or that is
+    reserved for the manager with ``role: manager``, starts a new
+    assignment, because one running worker cannot change any of them.
+    """
+    if item.owner != "agent":
+        # Automatic work inside the span drains within the assignment.
+        return True
+    if item.role == "manager" or (worker is not None and worker.role == "manager"):
+        return False
+    return worker is None or _worker_settings(worker) == _worker_settings(item)
+
+
+def _worker_settings(item: PlanItem) -> tuple[str | None, ...]:
+    return (
+        item.requested_agent,
+        item.requested_model,
+        item.requested_reasoning,
+        item.profile,
+    )
+
+
+@dataclass(frozen=True)
+class LoopSpan:
+    """Several body steps of one loop round that one worker performs."""
+
+    loop_id: str
+    stages: tuple[PlanItem, ...]
+
+    @property
+    def stage_names(self) -> tuple[str, ...]:
+        return tuple(dict.fromkeys(stage.name for stage in self.stages))
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "loop_assignment": "per_round",
+            "loop": self.loop_id,
+            "stages": list(self.stage_names),
+        }
+
+
+def loop_span(plan: WorkflowPlan, assignment: Assignment) -> LoopSpan | None:
+    """Return the loop body steps an assignment spans, when it spans several."""
+    stages = tuple(
+        item
+        for item in plan.items[assignment.start : assignment.stop]
+        if item.phase == "step" and item.owner == "agent" and item.loop_id is not None
+    )
+    if len(stages) <= 1:
+        return None
+    return LoopSpan(str(stages[0].loop_id), stages)
+
+
+@dataclass(frozen=True)
+class ItemSpan:
+    """Several per-item stages that one worker performs in one assignment."""
+
+    item_assignment: str
+    stages: tuple[PlanItem, ...]
+
+    @property
+    def item_ids(self) -> tuple[str, ...]:
+        return tuple(dict.fromkeys(str(stage.item_id) for stage in self.stages))
+
+    @property
+    def stage_names(self) -> tuple[str, ...]:
+        """The stage names of one item, in order."""
+        first = self.stages[0].item_id
+        return tuple(
+            dict.fromkeys(stage.name for stage in self.stages if stage.item_id == first)
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "item_assignment": self.item_assignment,
+            "item_ids": list(self.item_ids),
+            "stages": list(self.stage_names),
+        }
+
+
+def item_span(plan: WorkflowPlan, assignment: Assignment) -> ItemSpan | None:
+    """Return the per-item stages an assignment spans, when it spans several."""
+    stages = tuple(
+        item
+        for item in plan.items[assignment.start : assignment.stop]
+        if item.phase == "step" and item.owner == "agent" and item.item_id is not None
+    )
+    if len(stages) <= 1:
+        return None
+    return ItemSpan(stages[0].item_assignment, stages)
+
+
+def input_only(plan: WorkflowPlan, assignment: Assignment) -> bool:
+    """Whether an assignment holds no agent work, only values for handlers.
+
+    Such a span, for example a commit hook that needs its message after a
+    loop boundary, is not worth a worker: the manager has just read the
+    outcome it would summarize and supplies the values itself.
+    """
+    span = plan.items[assignment.start : assignment.stop]
+    # The built-in workflow summary trails the final assignment; it does not
+    # make a value-only span worth a worker.
+    return not any(item.owner == "agent" and not item.summary for item in span) and any(
+        item.requires_agent_input for item in span
+    )
+
+
+def active_assignment(
+    plan: WorkflowPlan, first_item_id: str | None, *, runtime: str
+) -> Assignment | None:
+    """Rebuild a persisted assignment after reload or plan materialization."""
+    if first_item_id is None:
+        return None
+    for index, item in enumerate(plan.items):
+        if item.id == first_item_id:
+            return assignment_at(plan, index, runtime=runtime)
+    return None
+
+
+def completion_window_items(
+    plan: WorkflowPlan, cursor: int, stop: int | None = None
+) -> tuple[PlanItem, ...]:
+    """Return the current item and the automatic items its completion feeds."""
+    items = [plan.items[cursor]]
+    for item in plan.items[cursor + 1 : stop]:
+        if item.owner == "agent" or workflow_transition(item) is not None:
+            break
+        items.append(item)
+    return tuple(items)
+
+
+def completion_window(
+    plan: WorkflowPlan, cursor: int, stop: int | None = None
+) -> tuple[tuple[ProvidedVariable, ...], tuple[str, ...]]:
+    """Return inputs required to complete the current assignment boundary."""
+    items = completion_window_items(plan, cursor, stop)
+    required: dict[str, ProvidedVariable] = {}
+    sources: dict[str, str] = {}
+    for item in items:
+        for value in item.provide:
+            source = f"{item.name} ({item.source}, {item.id})"
+            if value.name in required and required[value.name] != value:
+                raise StateError(
+                    f"completion window has conflicting provided variable "
+                    f"{value.name!r}: {sources[value.name]} and {source}"
+                )
+            required.setdefault(value.name, value)
+            sources.setdefault(value.name, source)
+    context = [item.name for item in items[1:]]
+    return tuple(required.values()), tuple(context)
+
+
+def _coordinator(item: PlanItem) -> bool:
+    return is_coordinator(item)