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

ww/assets/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/assets/workflows/catchall.yaml

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# catchall records a change no configured workflow covers. It exists so that
+# every change goes through ww, including the small ones an agent would
+# otherwise just make, without adding any process to them: the agent works
+# exactly as it would on a plain prompt and ww keeps the record.
+workflows:
+  - name: catchall
+    description: >-
+      Records a change to files that no other workflow covers, adding no
+      process of its own.
+    # A plain prompt leaves the agent free to delegate; so does this.
+    runtime: auto
+    # A new request on the same task replaces an unfinished one.
+    restartable: true
+    steps:
+      - name: work
+        description: >-
+          This workflow only records the request; it adds no process of its
+          own. Carry out the request exactly as you would if the user had
+          asked you directly, without ww: the same judgement, tools,
+          subagents, skills, and project conventions. Complete the step when
+          the work is done, with what you changed as the artifact.
+        # The session that received the prompt does the work, as it would
+        # without ww; any subagents it uses along the way are its choice.
+        role: manager

ww/assets/workflows/onboarding.yaml

@@ -0,0 +1,586 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# ww's learning and setup workflows. They learn how the project works, into
+# the one file ww keeps for its own use, and design a setup with the operator
+# from it, which ww places with `setup apply`. They never interview the
+# operator about who they are, their role, their team or their company: what
+# the setup needs of the operator is asked as process questions, in
+# conversation, and ends up in the proposal, not in a dossier. The `ww-*`
+# skills start them; `ww-setup` guides through them on a first use, express
+# (`ww-suggest` told to derive defaults) or not.
+#
+# The learning step always updates an existing file in place, so running the
+# workflow again refreshes it. None of them commits: the shared file is left
+# for the operator to review and commit.
+
+documents:
+  - project: >-
+      How this project's work is organised: tooling, trackers, infrastructure,
+      stack, conventions and recurring pitfalls. Shared with the team.
+    scope: project
+    path: .ww/project.md
+  - setup_proposal: >-
+      The configuration fragment a ww setup workflow proposes, which ww places
+      with `setup apply`.
+    path: .ww/tasks/{{ww.task.id}}/setup-proposal.yaml
+
+modes:
+  - ww-narrate: >-
+      The operator asked to see what ww does while it learns. Before each step,
+      tell them in one or two plain sentences what the step does and why; after
+      it, say what it found or changed and where.
+
+workflows:
+  - name: ww-learn-project
+    description: >-
+      Learns the repository (purpose, stack, verify commands, CI, review and
+      release process, conventions, pitfalls) into project.md.
+    runtime: single
+    restartable: true
+    role: manager
+    recommended_next_workflow: ww-suggest
+    steps:
+      - name: scan
+        description: >-
+          Learn the repository in {{ww.task.workspace_dir}}: what it is for,
+          in a sentence or two, and above all how its work is organised. Read
+          only; change no file. If {{ww.documents.project}} exists, read it
+          first: what it records is the project learning to refresh, so look
+          again only at what may have changed and keep the rest. First run
+          `{{ww.executable}} inspect` there and take its facts as the base, each with the evidence it names or "not found": the default
+          and integration branch, the branch patterns, merge or rebase and the
+          pull request signals; activity and team shape; the fix share and the
+          paths fixes touch; the manifests and their verify commands, each an
+          exact argument list such as `npm run lint`; the tracker key prefixes
+          with the candidate `task_format`; and the commit convention with the
+          candidate `commit_format`. Spend your own reading only on what
+          inspect cannot see, naming the file or command for each fact you
+          add: how and where commands run, on the host or through a wrapper
+          (a container exec such as `docker compose exec app`, a virtual
+          environment, a task runner), with the wrapper as an exact argument
+          list, and whether each worktree gets its own environment, from the
+          Makefile or task runner, the compose and devcontainer files, the CI
+          jobs and the agent instructions; what agents are allowed or
+          forbidden to do, from the content of
+          AGENTS.md, CLAUDE.md and cursor rules; what the pull request template
+          and CODEOWNERS demand; the process sections of the README and
+          CONTRIBUTING, such as reviews, releases and versioning; the gates the
+          CI files enforce; the workflows and conventions already in use,
+          including an existing ww setup (`ww.yaml`, `ww-setup.yaml`); and a verify command a document names that no
+          manifest does. Then, briefly, the agent tooling (MCP servers and
+          agent settings in .mcp.json, .claude/, .codex/, .cursor/, .gemini/,
+          skills and commands) and the stack (languages, frameworks, package
+          managers, containers, deployment). If {{ww.documents.project}}
+          exists, note what it says that no longer matches. The artifact is
+          the inspect profile, then the setup facts with what you added, then
+          the other findings.
+      - name: history
+        description: >-
+          Find the mistakes that come back. Read only. Start from the Fixes
+          section of the inspect profile: the fix share, the paths fixes touch
+          and the recent fix subjects. Read the full messages of those commits
+          (`git log --grep` or `git show --stat <commit>`) and, where `gh`,
+          `glab` or the tracker's MCP server is configured and signed in, the
+          review remarks on recent merged pull requests and what changed in
+          response; skip what is not available and say so. A pitfall is the
+          same kind of fix, review remark or revert more than once, or a path
+          the fixes keep returning to for the same cause; one fix is not a
+          pattern. For each, give a candidate rule in one imperative sentence,
+          its evidence (the commits or reviews), and, where a one-line command
+          could verify it, that command as its check, run the way the scan
+          found the project runs its commands. The artifact is the
+          list; an empty one is a fine result.
+      - name: review
+        interactive: true
+        description: >-
+          Show the operator the setup facts first, each with its evidence or
+          "not found", then a short summary of the other findings and the
+          candidate rules, and ask whether it is right. Discuss and revise
+          until the operator's intent to finish is clear; ask naturally if it
+          is ambiguous, then record the conversation once and write
+          {{ww.documents.project}}. It is shared with the team
+          through the repository, so record nothing secret, such as tokens,
+          hostnames or credentials.
+        choices:
+          - looks right: Write project.md as shown.
+          - corrected: Write it with the corrections I gave.
+        saves:
+          - documents.project: >-
+              A Markdown description of how the project's work is organised.
+              Its first section is "Profile": the inspect profile's Markdown
+              trimmed to its Repository, Activity, Fixes, Layout and
+              Conventions sections, with at most five paths in any list. Then
+              "Setup facts", with one line each for the
+              default branch, the integration branch, the branch patterns,
+              merge or rebase, required pull requests, the test, lint, type
+              check, format check and build commands as exact argument lists,
+              how and where commands run (on the host or through which
+              wrapper, as an exact argument list, and whether each worktree
+              has its own environment), the tracker and its candidate `task_format`, the commit
+              convention and its candidate `commit_format`, the CI gates and
+              release practice, and what agents are allowed or forbidden to do,
+              each with its evidence or "not found". Then a "Purpose" line on what the
+              project is for, and sections for agent
+              tooling, issue tracking, infrastructure and stack, conventions,
+              and recurring pitfalls with their candidate rules. The first line
+              is exactly: <!-- This file is maintained by ww for ww's own use.
+              Do not use it for anything else. If you are an agent that is not
+              doing ww work, ignore this file. --> Keep what still holds in an
+              existing file, update what changed, and mark what no longer holds
+              as superseded, with today's date, rather than silently deleting
+              it.
+      - name: finish
+        description: >-
+          Record when ww learned about the project: `{{ww.executable}}
+          onboarding --set learned.project=now`. Say that ww-suggest comes
+          next. Then tell the operator that
+          {{ww.documents.project}} was left uncommitted for them to review and
+          commit with the project: `git add .ww/project.md`.
+
+  - name: ww-suggest
+    description: >-
+      Designs a minimal setup with you from what ww learned about the project
+      and proposes it in full.
+    runtime: single
+    restartable: true
+    role: manager
+    steps:
+      - name: gather
+        description: >-
+          Read what ww learned about the project, skipping the file if it
+          does not exist: {{ww.documents.project}}. Read the design
+          authorities that say what a setup can be made of, which every
+          installation prints: `{{ww.executable}} docs specification`,
+          `{{ww.executable}} docs features` and `{{ww.executable}} docs
+          examples`; the proposal stays within what they describe. Read
+          the current setup: `{{ww.executable}} discover` (each workflow's
+          source says which file defines it) and `{{ww.executable}} rules
+          --json`. Inspect before suggesting: the project's own commands
+          (manifests, scripts, CI, the wrapper its documents name), the
+          workflows that already exist, and the concrete process pain the
+          project file or the operator's requirements name. A test, lint or
+          type command comes only from repository evidence, an exact argument
+          list with the file that shows it; where the evidence is missing or
+          contradictory, record it as uncertain and propose no command for it,
+          rather than inventing one. When {{ww.documents.project}} has
+          no "Profile" section, or does not exist, run `{{ww.executable}}
+          inspect` in {{ww.task.workspace_dir}} and take its facts; look up,
+          read only, only what neither has, such as what AGENTS.md, CLAUDE.md
+          and cursor rules let agents do. The artifact lists every fact a
+          setup decision can rest on, each with its evidence or "not found":
+          the branches and lanes, the verify commands and how and where they
+          run, the CI and review process, the kind of work each lane or
+          workflow the operator wants covers (code changes, manual testing,
+          reviews, reports), the team shape and cadence, the fix signals, the
+          candidate projects, the tracker key and commit convention, the
+          pitfalls the project file records, and what is already configured.
+          If {{ww.documents.project}} does not exist, tell the operator that
+          the proposal will be weaker without it and that the next step offers
+          to learn first; they may prefer to go on; say that the suggestions
+          then rest on the checkout alone. State whether the
+          requirements ask for an express setup.
+      - name: process
+        interactive: true
+        description: >-
+          Ask the operator about their process, a few questions that shape the
+          setup, in one message, numbered, each one plain sentence. Never ask
+          about who they are, their role, their team or their company; ask
+          only about the work. Skip what the gathered facts already answer,
+          saying so in a clause ("the project file records that reviews happen
+          in pull requests"), and ask only what is missing: (1) what is
+          painful in how work goes with agents or in this project today,
+          taking recurring pitfalls the facts list as the starting point; (2)
+          what outcome would help most; (3) where they want to be involved,
+          such as reviewing, approving a plan or testing by hand, and where an
+          agent may go on alone; (4) what may run automatically without them.
+          If the requirements ask for an express setup, ask none of these:
+          state the defaults the facts support for each, and ask only a
+          consequential choice that the facts leave open and that changes the
+          setup, such as who reviews when the project shows no review process.
+          Ask only what the gathered facts leave unanswered and what changes
+          the design. End your turn and wait for the answers; "skip" is a
+          valid answer.
+          Then converse: follow up where an answer deserves it and say what it
+          implies for the setup. Treat clear contextual completion as
+          permission to finish; ask naturally if it is ambiguous, then record
+          the conversation once. Keep the answers for the proposal: they
+          decide modes, operator stops, review and automation there, and are
+          not written to a file of their own. They never block ordinary work.
+      - name: design
+        interactive: true
+        description: >-
+          Settle with the operator what the setup turns on, in one message:
+          numbered items, each one plain sentence with its default and, in a
+          clause, the evidence for it, so that the operator only corrects;
+          list the options under an item that has a few. What the profile
+          already answers, and what the process answers, is stated as decided,
+          not asked. End your turn and
+          wait for the answers; "skip" keeps a default. Then discuss: follow
+          up where an answer deserves it and revise the decisions. Treat clear
+          contextual completion as permission to finish; ask naturally if it
+          is ambiguous, then record the conversation once. Cover:
+          (1) the integration branch and the lanes, from the branch patterns
+          actually present: feature work, plus a hotfix, bugfix or release
+          lane only where such branches exist or the operator asks for one,
+          and a merge back where there is an integration branch; (2) the
+          verify commands and their order, from the manifests, and how they
+          run: on the host or through the project's wrapper, in the task's
+          worktree when there is one; (3) whether
+          agents commit, following the commit convention (yes by default), and
+          push (never); (4) a worktree per task: on by default when several
+          contributors are active and the operator works on parallel tasks,
+          otherwise off; (5) the task ID format, from the tracker key prefixes,
+          or ww's generated IDs when there are none; (6) the review, from the review process the facts show and where the
+          operator wants to be involved: for a solo team shape, no interactive
+          review by default but an agent self-review step, and for a small
+          team or a team, the operator keeping the review in an interactive
+          step by default, an agent review loop being the alternative; (7) for each workflow whose work is not
+          a plain code change, such as manual testing, which step features it
+          needs and why, as the features guide's "Designing a workflow"
+          section says; (8) what the process answers turn into modes, such as brief
+          updates or asking first, and operator stops; (9) only when the layout lists candidate
+          projects, `projects`: ask for the paths of the sibling
+          repositories, which ww never scans; (10) a rule for a hot path or a
+          fix-prone path, only when the Fixes section shows a repeated cause
+          there, naming it; (11) last, for whom the setup is: the operator
+          alone, in local files kept out of version control, or the team, in
+          files committed with the project. If ww-setup.local.yaml exists
+          beside ww.yaml, an earlier run set ww up for the operator alone: say
+          so, and that this run can share that setup or refine it. If the
+          gather step found {{ww.documents.project}} missing, add to the last
+          item the option to learn first. The artifact lists every decision
+          with the fact or answer it rests on. The answer to the last item is
+          the choice. On "learn first" this run ends; tell the operator to run
+          ww-learn-project, which recommends ww-suggest when it completes.
+        choices:
+          - for me: Set it up for me alone; I can share it later.
+          - for the team: Set it up for the team, in the shared files.
+          - learn first: Let ww learn the project first; nothing changes.
+          - not now: Stop here; nothing changes. I can come back later.
+      - assess: >-
+          Did the operator choose "for me" or "for the team" in the design
+          step?
+      - name: setup
+        steps:
+          - name: propose
+            interactive: true
+            artifact_from: design
+            description: >-
+              Draft the complete setup from the facts and the design
+              decisions, in the shape of the examples (`{{ww.executable}} docs
+              examples`, the Node project one), sized to the project:
+              one test script gets one lane, a handler or two and the git
+              settings. Write it to {{ww.documents.setup_proposal}} as a
+              fragment with the root keys `workflows`, `modes`, `documents`,
+              `handlers`, `hooks` and `rules` in ww's YAML notation, plus
+              `settings` for ww.json: `task_format` from the tracker's key (its
+              prefix with `digit`), or `explicit` when every task carries the
+              tracker's ID; `projects` with the paths the operator gave; under
+              `extensions` and `ww/git`, `base_branches` (`default` the
+              integration branch, `hotfix` the release branch),
+              `branch_name_formats` per lane, `commit_format` after the commit
+              convention, `separate_branch: true`, and `worktrees` with
+              `worktree_dir` only when chosen; under `rules`, a
+              `check_guidance` only when {{ww.documents.project}} records a
+              wrapper that commands go through, such as a container: one or two
+              sentences telling `ww-scriptize-rules`, which scripts rules
+              into checks, where each check must run (through the wrapper, on the task's worktree) and
+              when the host may run one. `ww-scriptize-rules` automatically
+              branches from `extensions.ww/git.base_branches.default` (required)
+              and follows the ww/git worktree settings; it needs no workflow
+              lane setting. Add
+              `limits` only on request.
+
+
+              Design the workflows by the features guide (`{{ww.executable}} docs
+              features`, "Designing a workflow") and write exact syntax by the
+              specification (`{{ww.executable}} docs specification`): they say
+              where a command belongs (an ordinary step, a reusable handler or
+              a hook), when items, assessments, loops and modes are warranted,
+              and how ww/git lifecycle handlers attach to lanes; nothing
+              pushes. Give each lane a workflow: investigate, implement or
+              fix, and the review chosen in design; `inherit` for a lane that
+              differs only in its base branch, a `merge-to-<integration
+              branch>` lane where there is one, and `recommended_next_workflow`
+              where lanes chain.
+
+
+              Every command the fragment carries, a handler's step, a hook's
+              `argv` or `shell`, a rule's check and a script, runs the way
+              the project runs its commands: ww runs it from the step's
+              directory, the task's worktree when worktrees are on, so write
+              it for that directory, through the project's wrapper where it
+              has one, following the `check_guidance` that `{{ww.executable}}
+              rules --json` shows when it is set, and never name the main
+              checkout's absolute path or `cd` out of it.
+
+
+              Keep each workflow as simple as its work allows and add a feature only
+              for the concrete reason the guide gives. Never redefine a
+              workflow ww ships (`catchall`, `ww-*`), duplicate what is
+              configured, or edit ww's configuration files yourself. A
+              workflow the project already defines is changed with
+              `{{ww.executable}} setup update`, not by a second definition.
+
+
+              For each proposed workflow, in this order: (1) state its
+              trigger, the result it should give and where the operator is
+              involved, in a few lines; (2) choose the smallest structure that
+              expresses them; (3) show concise YAML and a short walkthrough of
+              a representative task, with a failure and retry path wherever an
+              external effect or an automatic command is involved; (4) validate
+              and inspect, below, and fix the draft before asking; (5) ask to
+              apply it. Commands come from the repository evidence of the
+              gather step; show a command it could not settle as an open
+              question, never as a guess. Preserve every requirement the
+              operator stated, rather than shortening the YAML.
+
+
+              Validate the composed configuration and inspect what it
+              compiles to: `{{ww.executable}} setup apply
+              {{ww.documents.setup_proposal}} --for <me or team, as chosen in
+              design> --dry-run --inspect <the main lane> --agent <your
+              agent>` and fix the fragment until it passes. In the compiled
+              plan check that automation is ww-owned (a command runs as a
+              handler or hook, and no step asks the agent to run it), that
+              item scopes are valid, and that the operator meets only the
+              conversations intended. Present it section by section
+              (settings, handlers, workflows, hooks, modes, rules), each piece
+              with its evidence in one clause, such as "`hotfix` lane: 14
+              `hotfix/*` branches merged this year" or "`run-tests` runs `npm
+              test`: `package.json` scripts", then the dry run's changes. Then
+              walk through the main lane: its steps in order with what an agent
+              does at each and where ww runs checks automatically without an
+              agent prompt, from the fragment, in ten lines or fewer. Ask
+              whether to apply it; discuss and take changes, validating and
+              showing it again until the operator's intent to finish is clear;
+              ask naturally if it is ambiguous, then record the conversation
+              once with their pick, apply or cancel. The pick is the approval
+              of this exact edit: do not ask again before applying it.
+            choices:
+              - apply: Apply it as shown.
+              - cancel: Do not apply anything.
+            saves:
+              - documents.setup_proposal: >-
+                  The setup fragment as the operator last saw it.
+          - assess: Did the operator choose "apply" in the propose step?
+          - name: apply
+            description: >-
+              Place the setup the operator agreed to: `{{ww.executable}} setup
+              apply {{ww.documents.setup_proposal}} --for <me or team, as
+              chosen in design> --yes`. Then run `{{ww.executable}} lint` and
+              show its result, and run `{{ww.executable}} plan --workflow <the
+              main lane> --agent <your agent>` and show the operator its first
+              step's page as "what an agent gets on the first task". Tell the
+              operator which files changed, naming
+              each as the output lists it. For the team, they are
+              ww-setup.yaml, ww.yaml and ww.json, left uncommitted: remind the
+              operator to review and commit them, for example `git add
+              ww-setup.yaml ww.yaml ww.json`. For the operator alone, they are
+              local files and nothing is committed; running ww-suggest again
+              and choosing the team offers the same setup to the team. If
+              `setup apply` refuses, show its message and stop; never place the
+              configuration another way.
+
+  - name: ww-solve
+    description: >-
+      Turns a problem you describe into proposed workflows, modes, rules or
+      hooks.
+    runtime: single
+    restartable: true
+    role: manager
+    steps:
+      - name: listen
+        interactive: true
+        description: >-
+          Ask the operator to describe the problem: what goes wrong, how often,
+          and what it costs them. Ask a few clarifying questions, one at a
+          time, then restate the problem in two or three sentences and ask
+          whether that is it.
+      - name: propose
+        interactive: true
+        description: >-
+          Read what ww learned about the project, skipping the file if it
+          does not exist: {{ww.documents.project}}; and the current
+          setup: `{{ww.executable}} discover` and `{{ww.executable}} rules
+          --json`. Propose the smallest change that addresses the problem: a
+          workflow or a step, a mode, a rule, a hook, or a setting. Let
+          the problem decide what it asks of the operator: what it must always
+          hold gets rules and checks, what can be handed over gets handoffs,
+          and decisions the operator keeps become operator stops or
+          interactive steps. Where the problem is about a kind of work, choose
+          the structure by the features guide (`{{ww.executable}} docs
+          features`, "Designing a workflow"), and write exact syntax by the
+          specification (`{{ww.executable}} docs specification`). Write every command it carries, a hook's `argv` or `shell`, a
+          rule's check or a script, for the step's directory, the task's
+          worktree when worktrees are on, through the project's wrapper as
+          {{ww.documents.project}} records it and as the `check_guidance` of
+          `{{ww.executable}} rules --json` says when it is set, never with
+          the main checkout's absolute path. Write it as a setup fragment to
+          {{ww.documents.setup_proposal}} (the root keys `workflows`, `modes`,
+          `documents`, `handlers`, `hooks`, `rules` and `settings`; rules as
+          literal sentences in the `rules` lists of the steps they govern). A
+          fragment adds definitions; to change a workflow the configuration
+          already defines, write the complete changed workflow alone in the
+          fragment (its `workflows` list holding that one entry) and apply it
+          with `{{ww.executable}} setup update <name> <fragment>`, which
+          edits the definition in force where it is written. Never
+          edit ww's configuration files yourself. Check the fragment with
+          `{{ww.executable}} setup apply {{ww.documents.setup_proposal}} --for
+          me --dry-run` (or `setup update <name> <fragment> --dry-run`) until
+          it passes. Show the operator what each piece does
+          and why, with the dry run's list of changes, and ask where to apply
+          it.
+        choices:
+          - for me: Apply it to my local setup.
+          - for the team: Apply it to the shared setup.
+          - update: Change the existing workflow where it is defined.
+          - cancel: Do not apply anything.
+        saves:
+          - documents.setup_proposal: >-
+              The setup fragment as the operator last saw it.
+      - assess: >-
+          Did the operator choose "for me", "for the team" or "update" in the
+          propose step?
+      - name: apply
+        description: >-
+          Place the change: `{{ww.executable}} setup apply
+          {{ww.documents.setup_proposal}} --for <me or team, as chosen> --yes`
+          or, for "update", `{{ww.executable}} setup update <name>
+          {{ww.documents.setup_proposal}} --yes`, then run `{{ww.executable}} lint` and show its result. Tell the
+          operator which files changed; shared ones are left uncommitted for
+          them to review and commit. If `setup apply` refuses, show its message
+          and stop; never place the configuration another way.
+
+  - name: ww-rules-from-artifacts
+    description: >-
+      Proposes rules from the lessons that recur in chosen steps' past results.
+    runtime: single
+    restartable: true
+    role: manager
+    steps:
+      - name: choose
+        interactive: true
+        description: >-
+          Run `{{ww.executable}} discover` and list the workflows and their
+          steps. Ask the operator which steps' results to learn from (review
+          and fix steps are good sources) and how many recent tasks to read;
+          ten is a sensible default. Offer the step names through your question
+          tool.
+      - name: read
+        description: >-
+          Find the recent tasks that ran the chosen steps: the task directories
+          under `.ww/tasks/` at the project root, newest first, and for each
+          `{{ww.executable}} artifacts <task-id>` (add `--run <run-id>` for an
+          earlier run). Read only the artifacts of the chosen steps. Collect
+          the lessons that recur in more than one task, such as the same review
+          finding or the same fix, and skip one-off defects. Read
+          `{{ww.executable}} rules --json` and drop lessons an existing rule
+          already covers. Read {{ww.documents.project}} where it exists, and keep each
+          lesson within what it says: the project's conventions decide what a
+          rule may demand. The artifact lists each lesson with
+          the tasks that show it.
+      - name: propose
+        interactive: true
+        description: >-
+          Turn each lesson into a candidate rule: one imperative sentence, with
+          a `paths` glob only when it is about a kind of file, and a check only
+          when it is an obvious one-line command, written for the step's
+          directory (the task's worktree when there is one) and run through
+          the project's wrapper as {{ww.documents.project}} records it,
+          following the `check_guidance` of `{{ww.executable}} rules --json`
+          when it is set. Choose the rule group it
+          belongs to from `{{ww.executable}} rules --json`, or a new group with
+          the workflows and steps it concerns. Show the operator all candidates
+          in one block, each with its group, the steps it will reach, and the
+          evidence, and ask which to add. Keep them few and gentle.
+        choices:
+          - add all: Add every rule shown.
+          - add some: Add the ones I named.
+          - none: Add nothing.
+      - assess: Did the operator choose to add any rule in the propose step?
+      - name: add
+        description: >-
+          Add the rules the operator accepted, only through ww's rule commands,
+          each checked with `--dry-run` first: a new group with
+          `{{ww.executable}} rules add --group <name> --dir <path> [--workflows
+          <name>...] [--steps <name>...]`, then each rule with
+          `{{ww.executable}} rules add <group> --text "<sentence>" [--paths
+          <glob>...]`. Never edit a rule file or ww's configuration files
+          yourself; report a refusal instead of working around it. Run
+          `{{ww.executable}} lint`, show where each rule now applies, and tell
+          the operator that the new rule files and ww-rules.yaml are left
+          uncommitted for them to review and commit.
+
+  - name: ww-automate
+    description: >-
+      Proposes a script for a step's mechanical work, and the handler that runs
+      it.
+    runtime: single
+    restartable: true
+    role: manager
+    steps:
+      - name: choose
+        interactive: true
+        description: >-
+          Run `{{ww.executable}} discover` and list the workflows and their
+          steps. Ask the operator which step to look at, offering the step
+          names through your blocking question tool or as a numbered list in
+          the chat.
+      - name: analyse
+        description: >-
+          Read the chosen step's instruction (`{{ww.executable}} plan
+          --workflow <workflow> --agent <your agent>`) and what it produced in
+          recent tasks (`{{ww.executable}} artifacts <task-id>` for the task
+          directories under `.ww/tasks/` at the project root). Decide which
+          parts of its work are mechanical, the same every time and needing no
+          judgement: running commands, collecting or reformatting data, filling
+          a template, checking a condition. The artifact says what could be a
+          script, what must stay with an agent, and whether the script would
+          replace the step or run beside it, by the features guide's
+          "Designing a workflow" section (`{{ww.executable}} docs features`). Read
+          {{ww.documents.project}} where it exists, and keep the proposal
+          within what it says: the project's conventions decide what a script
+          may automate.
+          If nothing is mechanical, say so; that is a fine result.
+      - name: propose
+        interactive: true
+        description: >-
+          If the analysis found nothing to automate, tell the operator and
+          offer only "cancel". Otherwise draft the script (shell or the
+          project's own language, small, with a clear exit status) and the
+          handler change as a setup fragment in
+          {{ww.documents.setup_proposal}}: a hook that runs it, filtered to the
+          workflow and step with `workflows` and `steps`, or, for a workflow
+          the configuration defines, that workflow with the step turned into an
+          `argv` or `shell` step. To change a workflow the configuration
+          already defines, write the complete changed workflow alone in the
+          fragment and place it with `setup update`, which edits the
+          definition in force. Never edit ww's configuration files
+          yourself. ww runs the script from the step's directory, the task's
+          worktree when worktrees are on: write it for that directory, run
+          the project's tools through its wrapper as
+          {{ww.documents.project}} records it, and never name the main
+          checkout's absolute path. Check the fragment with
+          `{{ww.executable}} setup apply {{ww.documents.setup_proposal}} --for
+          me --dry-run`. Show the operator the script, where it would live, and the dry run's list of
+          changes, and ask where to apply it.
+        choices:
+          - for me: Apply it to my local setup.
+          - for the team: Apply it to the shared setup.
+          - cancel: Do not apply anything.
+        saves:
+          - documents.setup_proposal: >-
+              The setup fragment as the operator last saw it.
+      - assess: >-
+          Did the operator choose "for me" or "for the team" in the propose
+          step?
+      - name: apply
+        description: >-
+          Write the script where the operator agreed, make it executable, and
+          run it once on a harmless input if it has one. Then place the handler
+          change: `{{ww.executable}} setup apply
+          {{ww.documents.setup_proposal}} --for <me or team, as chosen> --yes`,
+          and run `{{ww.executable}} lint`. Tell the operator which files
+          changed and that they are left uncommitted for them to review and
+          commit. If `setup apply` refuses, show its message and stop.