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

ww/assets/docs/examples.md

@@ -0,0 +1,879 @@
+# Examples
+
+Runnable examples for [the specification](specification.md), which defines
+every key exactly, and [the features guide](features.md), which says when to
+use what. Each example is a complete `ww.yaml`, unless it says otherwise, and
+the test suite loads and compiles every one; the behavioral ones are also run
+in a temporary project with fake commands. The first six are the ones to start
+from; the rest are larger compositions. Agent-facing text is
+deliberately brief; in a real project the descriptions carry the instructions
+your agents need.
+
+Read these documents from any installation with `ww docs examples`,
+`ww docs features` and `ww docs specification`.
+
+Run any of them with:
+
+```console
+./ww discover
+./ww start TASK-1 --workflow <name> --agent codex --requirements "<requirements>" --role manager
+```
+
+## 1. A linear workflow with an automatic check
+
+Plain agent steps in order, and a command ww runs itself. The implicit `init`
+step records the requirements first. `verify` is an ordinary visible step: ww
+runs it when it is reached, advances when it passes, and on a failure hands the
+output to an agent to fix (`on_failure: fix`) and runs it again.
+
+```yaml
+workflows:
+  - name: task
+    description: Implement a change and verify it.
+    steps:
+      - develop: Implement the requested change, with tests.
+      - verify: ~
+        argv: [python3, -m, pytest, -q]
+        on_failure: fix
+      - document: Update the documentation the change affects.
+```
+
+## 2. A natural interactive review
+
+An interactive step is a conversation held by the session the operator talks
+to. `choices` lists the answers the operator may pick, and `{{ww.choices}}`
+puts their labels into the instruction as a JSON array. It is guidance only:
+the operator may also just talk, and the agent finishes when their intent is
+clear.
+
+```yaml
+workflows:
+  - name: reviewed-change
+    steps:
+      - develop: Implement the requested change.
+      - review: >-
+          Walk the operator through the change and take their verdict. They
+          may answer with one of {{ww.choices}} or in their own words.
+        interactive: true
+        choices:
+          - approve: The change is fine as it is.
+          - rework: More changes are needed; the operator says which.
+```
+
+## 3. One item per piece with `items: ~`
+
+`items: ~` is the whole item lifecycle in one line: the step's own work is to
+split the task into items with `add-item`, and every item then gets one stage
+that analyzes, resolves and reports it. A string instead of `~` gives the
+splitting guidance. Use it when each piece is independent and one pass over
+it is enough.
+
+```yaml
+workflows:
+  - name: migrate-calls
+    steps:
+      - collect: Find every file that still calls `old_api`.
+        items: One item per file, with the file path as its ID.
+      - summarize: Summarize what changed.
+```
+
+## 4. One analysis, one fix, one report per comment
+
+Review comments often share causes, so they are analyzed and fixed together
+once, while every comment is still checked and answered on its own. The
+workflow has one item collection and several passes over it; the ordinary
+steps between the passes run once. The last pass reports each comment with the
+project's own script (not part of ww; `scripts/reply-to-comment.py` posts or
+updates one reply and prints the reply ID). ww passes values to it as
+arguments, saves the printed ID into the item, and marks the item reported
+once the command succeeds. `identity` and `unique` make the comment ID the
+item's identity, so no comment becomes two items.
+
+```yaml
+workflows:
+  - name: review-comments
+    steps:
+      - collect: Record one item per review comment, using its source ID.
+        items:
+          identity: comment_id
+          unique: [comment_id, reply_id]
+          steps: []
+      - analyze-together: >-
+          Analyze all collected comments together and record each analysis
+          with `update-item`.
+      - confirm-analysis: Reuse the collected items.
+        items:
+          steps:
+            - analyze: Check the shared analysis for this comment; fill gaps.
+              item_phase: analyze
+      - fix-together: >-
+          Implement and verify the fixes for all analyzed comments. Record the
+          result of each with `update-item --actual-solution ... --resolved=true`.
+      - report: Reuse the collected items.
+        items:
+          steps:
+            - reply: ~
+              item_phase: report
+              argv:
+                - python3
+                - scripts/reply-to-comment.py
+                - "{{ww.item.field.comment_id}}"
+                - "{{ww.item.actual_solution}}"
+                - "{{ww.item.field.reply_id}}"
+              saves:
+                - item.field.reply_id: The reply ID the script printed.
+```
+
+Re-running the script with a saved `reply_id` must update that reply instead
+of creating another: if ww stops after the remote call but before it saves the
+result, the next attempt runs the command again, and the script owns that
+idempotency.
+
+## 5. Assessments
+
+An assessment asks the agent for a judgment and routes the rest of the
+workflow. The compact form takes only a question: `positive` continues,
+`negative` completes the workflow. The standard branches can sit beside
+`question`, each one an ordinary step shape, and an undeclared branch runs
+nothing and continues. With labels of your own, wrap the branches in
+`outcomes`; each one here is a direct handler. The agent picks with
+`next --outcome <label>`.
+
+```yaml
+handlers:
+  - name: apply-migration
+    argv: [python3, scripts/migrate.py]
+  - name: ask-for-fixes
+    description: Ask the author to fix the migration.
+
+workflows:
+  - name: gate
+    steps:
+      - build: Implement the change.
+      - assess: Is the change ready for review?
+      - review: Review the change.
+
+  - name: branches
+    steps:
+      - assess:
+          question: Does the change touch public behavior?
+          positive:
+            steps:
+              - changelog: Add a changelog entry.
+          negative:
+            steps:
+              - note: Record that the change is internal.
+      - wrap-up: Summarize the change.
+
+  - name: migrate
+    steps:
+      - dry-run: Run the migration against a scratch database.
+      - assess:
+          question: How did the dry run go?
+          outcomes:
+            clean:
+              handler: apply-migration
+            needs-fixes:
+              handler: ask-for-fixes
+```
+
+## 6. Global, project and local variants
+
+Workflows come from up to three levels: your global file (`~/.config/ww/ww.yaml`,
+or `$WW_USER_CONFIG_DIR`), the project's committed `ww.yaml`, and an uncommitted
+`ww.local.yaml` beside it. A lower level replaces a same-named definition from
+above and adds its own; handlers, modes and the rest compose the same way.
+`discover` shows where each workflow comes from and lists local, then project,
+then global, which is the order to prefer when several fit; an explicit request
+for a workflow always wins. Each block below is a separate file, marked by its
+first line.
+
+```yaml
+# file: ~/.config/ww/ww.yaml
+handlers:
+  - name: test
+    argv: [python3, -m, pytest, -q]
+
+workflows:
+  - name: task
+    description: Implement a change, my default.
+    steps:
+      - develop: Implement the change.
+  - name: standup
+    description: Summarize yesterday's work.
+    steps:
+      - summarize: Summarize what changed since yesterday.
+```
+
+```yaml
+# file: ww.yaml
+workflows:
+  - name: task
+    description: Implement a change the way this project does.
+    steps:
+      - develop: Implement the change with tests.
+      - test: ~
+  - name: review
+    description: Review a pull request against the team's checklist.
+    steps:
+      - read: Read the change and report what to fix.
+```
+
+```yaml
+# file: ww.local.yaml
+workflows:
+  - name: review
+    description: Review a pull request, findings first.
+    steps:
+      - read: Read the change and list the findings, worst first.
+```
+
+Here `task` is the project's (it replaces the global one and still uses the
+global `test` handler), `review` is the local one, and `standup` comes from the
+global file.
+
+## 7. Hooks and reusable handlers
+
+Hooks are for lifecycle invariants: something that must happen at a fixed
+point of every matching step or workflow, such as a clean tree before a task
+starts. A command that is merely a visible operation of the workflow belongs
+in an ordinary step (example 1); being automatic does not make it a hook.
+Handlers are defined once, so a step or a hook can reuse them. Global hooks apply to every
+workflow, a workflow's hooks to one workflow, and step hooks to one step.
+Automatic handlers, here `argv` commands, run by ww itself; the agent never
+executes them. `assert` lists conditions the command's output must meet. `idempotent: true` says
+that running the handler again is harmless, so when ww is interrupted while
+it runs, the next `next` replays it instead of stopping for an operator
+decision; leave it off a handler whose replay could do damage, such as a
+publish or a commit.
+
+```yaml
+handlers:
+  - name: lint
+    description: Run the linters.
+    argv: [ruff, check, src]
+    idempotent: true
+  - name: verify-clean
+    argv: [printf, clean]
+    assert:
+      - equals: clean
+  - name: announce
+    description: Tell the team what changed.
+
+hooks:
+  before_start_workflow:
+    - workflows: [task]
+      handlers:
+        - verify-clean: ~
+  before_complete_workflow:
+    - handlers:
+        - announce: ~
+
+workflows:
+  - name: task
+    hooks:
+      before_start:
+        - steps: [develop]
+          handlers:
+            - lint: ~
+    steps:
+      - develop: Implement the change.
+        hooks:
+          after_complete:
+            - lint: ~
+      - review: Review the change.
+```
+
+## 8. Shell commands with arguments, environment, and variables
+
+Shell source never interpolates directly; data goes through `args` and `env`.
+`variables` asks the agent for values that later automatic steps consume, and
+`{{...}}` interpolates them. `artifact: false` skips the artifact for a step
+whose result is only its variable. Every value ww provides itself lives under
+`ww.`, such as `{{ww.task.id}}`.
+
+```yaml
+workflows:
+  - name: release
+    steps:
+      - pick-version: Decide the next version number.
+        artifact: false
+        variables:
+          - version: The next semantic version, for example 1.4.0.
+      - tag:
+        shell: 'git tag -a "v$1" -m "$MESSAGE"'
+        args: ["{{version}}"]
+        env:
+          MESSAGE: "Release {{version}} for {{ww.task.id}}"
+      - notes: Write the release notes for {{version}}.
+```
+
+## 9. Modes, profiles, and execution settings
+
+Modes are selectable guidance, profiles describe how an agent should behave,
+and `agent`, `model`, and `reasoning` are advisory requests the manager sees in
+the `auto` runtime. `role: manager` keeps a step in the managing session.
+
+```yaml
+modes:
+  - economy: Use as few tokens as possible and keep artifacts short.
+  - thorough: Prefer completeness over speed; verify every claim.
+
+profiles:
+  developer: Prefer small, well-tested changes and explain trade-offs briefly.
+  reviewer: Look for defects and missing tests; do not restyle code.
+
+workflows:
+  - name: feature
+    modes: [economy]
+    profile: developer
+    model: opus
+    reasoning: high
+    steps:
+      - plan: Outline the change before touching code.
+        role: manager
+      - implement: Implement the plan.
+      - review: Review the implementation.
+        profile: reviewer
+        agent: claudecode
+```
+
+## 10. Skills, slash commands, and MCP actions
+
+A step can require a discovered agent skill or slash command instead of plain
+prompt text (`kind: skill` or `kind: slash_command`), or address an MCP
+connection. The examples below need a
+`review-code` skill and a `ship` slash command in the agent's directory.
+
+```yaml
+workflows:
+  - name: ship
+    steps:
+      - review-code: Review the change with the project's review skill.
+        kind: skill
+      - create-ticket: Create the release ticket and record its key.
+        mcp: jira
+        variables:
+          - ticket: The key of the created ticket.
+      - ship: Run the release command.
+        kind: slash_command
+```
+
+## 11. Nested steps and artifact dependencies
+
+`steps` groups related work under a parent step that becomes in progress with
+its first child and completes with its last. `artifact_from` hands an earlier
+step's artifact to a later one: a sibling at the same nesting level, or an
+earlier step of an enclosing level, as `write-migration` does with `analyze`.
+
+```yaml
+workflows:
+  - name: migration
+    steps:
+      - analyze: Analyze the current schema and list the required changes.
+      - implement:
+        steps:
+          - write-migration: Write the migration.
+            artifact_from: analyze
+          - adapt-code: Adapt the code that reads the changed tables.
+            artifact_from: write-migration
+      - verify: Run the migration against a scratch database.
+        artifact_from: analyze
+```
+
+## 12. Loops with break and continue
+
+A `loop` repeats its body until a worker breaks it or the round limit is
+reached. `break` and `continue` are natural-language conditions the worker
+evaluates after doing the step. `max_rounds` overrides the project default, `limits.rounds` in
+`ww.json`.
+
+```yaml
+workflows:
+  - name: review-and-fix
+    steps:
+      - implement: Implement the change.
+      - polish:
+        max_rounds: 4
+        loop:
+          - review: Review the current state of the change.
+            break: There are no meaningful findings left.
+          - triage: Decide whether the findings are worth fixing now.
+            continue: The findings are cosmetic and can be batched into the next review.
+          - fix: Fix the findings.
+```
+
+## 13. A handoff workflow that chooses the next one
+
+A workflow that ends in a transition step, `handoff_to` beside the step name,
+hands off to another workflow, which continues as the next run of the same
+task; the transition alone makes it a handoff workflow. This is how one entry
+point routes a request to the right process.
+
+```yaml
+workflows:
+  - name: route
+    steps:
+      - classify: Decide whether this request is a bug fix or a feature.
+        artifact: false
+        variables:
+          - workflow: One of the workflows listed in {{ww.task.workflows}}, other than route.
+      - route: ~
+        handoff_to: "{{workflow}}"
+
+  - name: bugfix
+    steps:
+      - reproduce: Reproduce the bug.
+      - fix: Fix it and add a regression test.
+
+  - name: feature
+    steps:
+      - implement: Implement the feature.
+      - test: Test it.
+```
+
+## 14. Parent and child tasks
+
+A `children` step collects independent pieces of work and runs a workflow for
+each as its own task under the parent. Children run one at a time; the parent
+continues when the last child completes. Until a child starts, `update-child`
+can still change its text or project.
+
+```yaml
+workflows:
+  - name: epic
+    steps:
+      - split: Split the epic into independent stories.
+        children:
+          description: One child per story a user would notice.
+          workflow: story
+      - summarize: Summarize what the stories delivered.
+
+  - name: story
+    steps:
+      - implement: Implement this story.
+      - test: Test it.
+```
+
+When the parent has work of its own around each child, list its stages under
+`children.steps` instead of naming one workflow. The parent runs them once per
+child, one child at a time; the stage with `workflow:` runs the child and waits
+for it, and its artifact is the child's summary. Here the parent refines each
+story before it starts, reviews it afterwards, and a `break` on the review ends
+the epic early: the stories not started yet are skipped.
+
+```yaml
+workflows:
+  - name: epic
+    steps:
+      - split: Split the epic into independent stories.
+        children:
+          description: One child per story a user would notice.
+          steps:
+            - refine: Sharpen {{ww.child.text}} with what earlier stories taught.
+              role: manager
+            - implement:
+                workflow: story
+            - review: Check that {{ww.child.id}} delivered what it promised.
+              artifact_from: implement
+              break: The epic is complete; no remaining story is worth building.
+      - summarize: Summarize what the stories delivered.
+
+  - name: story
+    steps:
+      - implement: Implement this story.
+      - test: Test it.
+```
+
+## 15. Children that bind their own Jira IDs
+
+When the child workflow's first step declares the variable `task_id`, each child obtains its
+own external ID from that step when it starts. The parent's collection step
+tells the agent not to pass `--id`. The same first step lets the parent itself
+get its ID when started without one.
+
+```yaml
+workflows:
+  - name: epic
+    steps:
+      - create-epic: Create the Jira epic and return its key.
+        mcp: jira
+        variables:
+          - task_id: The epic key returned by Jira.
+      - split: Split the epic into stories.
+        children:
+          workflow: story
+
+  - name: story
+    steps:
+      - create-story: Create the Jira story for this child and return its key.
+        mcp: jira
+        variables:
+          - task_id: The story key returned by Jira.
+      - implement: Implement {{ww.task.id}}.
+```
+
+## 16. Saved metadata and project-scoped values
+
+`saves` persists values an agent produces. A `metadata.<path>` entry stays with
+the task; a `project_metadata.<path>` entry is shared by every task and read
+back through `{{ww.project_metadata.<path>}}`. The agent passes each as
+`--metadata <path>=<value>`, a project one as
+`--metadata project_metadata.<path>=<value>`.
+
+```yaml
+workflows:
+  - name: dependency-update
+    steps:
+      - update: Update the dependencies and note the highest risk change.
+        saves:
+          - metadata.dependencies.riskiest_change: The dependency whose update is most likely to break something.
+          - project_metadata.dependencies.last_update: Today's date in YYYY-MM-DD format.
+      - verify: Pay special attention to {{ww.metadata.dependencies.riskiest_change}}.
+```
+
+## 17. Git branches, commits, and worktrees
+
+Git integration is the bundled `ww/git` extension. Its handlers are referenced
+like any other, and its settings live in `ww.json`.
+
+```yaml
+hooks:
+  before_start_workflow:
+    - handlers:
+        - ext/ww/git/handlers:is-git-clean: ~
+        - ext/ww/git/handlers:start-task-branch: ~
+        - ext/ww/git/handlers:create-worktree: ~
+  before_complete_workflow:
+    - handlers:
+        - ext/ww/git/handlers:git-commit: ~
+        - ext/ww/git/handlers:remove-task-worktree: ~
+
+workflows:
+  - name: task
+    modes: [ext/ww/git/modes:conventional-commits]
+    steps:
+      - develop: Implement the change in the task worktree.
+      - test: Run the tests.
+```
+
+```json
+{
+  "enabled": true,
+  "limits": {"rounds": 3, "fixes": 3},
+  "extensions": {
+    "ww/git": {
+      "commit_format": "{{ww.task.id}}: {{commit_message}}",
+      "base_branches": {"default": "main", "hotfix": "release"},
+      "separate_branch": true,
+      "branch_name_formats": {
+        "default": "feature/{{ww.task.id}}",
+        "hotfix": "hotfix/{{ww.task.id}}"
+      },
+      "worktrees": true,
+      "worktree_dir": "./ww-worktrees",
+      "worktree_name_format": "{{ww.task.id}}"
+    }
+  }
+}
+```
+
+## 18. One ww instance over several repositories
+
+With `projects` in `ww.json`, the ww root is a workspace above
+the repositories. `start --project` and `add-child --project` choose where a
+task works, and the git extension follows.
+
+```json
+{
+  "enabled": true,
+  "projects": [
+    {"name": "backend", "path": "./backend", "description": "Python API service."},
+    {"name": "frontend", "path": "./frontend", "description": "React web client."}
+  ],
+  "extensions": {
+    "ww/git": {
+      "separate_branch": true,
+      "base_branches": {"default": "main"},
+      "branch_name_formats": {"default": "feature/{{ww.task.id}}"}
+    }
+  }
+}
+```
+
+A repository with conventions of its own states them in its own
+`ww.json`; only its `extensions` section is read, key by
+key over the root's, so `frontend/ww.json` needs nothing
+but what differs:
+
+```json
+{
+  "extensions": {
+    "ww/git": {
+      "base_branches": {"default": "master"},
+      "commit_format": "[{{ww.task.id}}] {{commit_message}}"
+    }
+  }
+}
+```
+
+```yaml
+hooks:
+  before_start_workflow:
+    - workflows: [feature]
+      handlers:
+        - ext/ww/git/handlers:is-git-clean: ~
+        - ext/ww/git/handlers:start-task-branch: ~
+  before_complete_workflow:
+    - workflows: [feature]
+      handlers:
+        - ext/ww/git/handlers:git-commit: ~
+        - ext/ww/git/handlers:return-to-base-branch: ~
+
+workflows:
+  - name: change
+    description: A change that may touch several repositories.
+    steps:
+      - split: Split the change into one child per repository.
+        children:
+          workflow: feature
+
+  - name: feature
+    steps:
+      - develop: Implement this part in {{ww.project.dir}}.
+      - test: Run this repository's tests.
+```
+
+```console
+./ww start CHANGE-1 --workflow change --agent codex --requirements "..." --role manager
+./ww add-child CHANGE-1 --id api --text "API part" --project backend
+./ww add-child CHANGE-1 --id web --text "Web part" --project frontend
+```
+
+## 19. A copied workflow, an early stop, and a recommended successor
+
+`bugfix` is `hotfix` under another name, so `ww/git` gives it its own branch
+format and base branch. `hotfix` recommends `merge-to-dev` when it completes,
+and the operator confirms before it starts. The merge's assessment stops the
+workflow outright when nothing needs a second look.
+
+```json
+{
+  "extensions": {
+    "ww/git": {
+      "separate_branch": true,
+      "base_branches": {"default": "main", "bugfix": "dev"},
+      "branch_name_formats": {
+        "default": "feature/{{ww.task.id}}",
+        "hotfix": "hotfix/{{ww.task.id}}",
+        "bugfix": "bugfix/{{ww.task.id}}"
+      }
+    }
+  }
+}
+```
+
+```yaml
+hooks:
+  before_start_workflow:
+    - workflows: [hotfix]
+      handlers:
+        - ext/ww/git/handlers:start-task-branch: ~
+
+workflows:
+  - hotfix: Fix a bug on main.
+    recommended_next_workflow: merge-to-dev
+    steps:
+      - investigate: Find the cause.
+      - fix: Fix it.
+
+  - bugfix: Fix a bug on dev.
+    inherit: hotfix
+    recommended_next_workflow: ~
+
+  - merge-to-dev: Merge the task's branch into dev.
+    steps:
+      - merge: Merge the branch into dev and resolve any conflicts.
+      - assess:
+          question: Were conflicts resolved in non-trivial code?
+          outcomes:
+            positive:
+              steps:
+                - review: Review each resolution against both branches.
+            negative:
+              stop_workflow: true
+      - verify: Run the tests and fix what fails.
+```
+
+The `start-task-branch` hook is written for `hotfix` and also runs for
+`bugfix`, which clears the recommendation it would otherwise inherit.
+
+## 20. Rules, checks, and the fix loop
+
+Rules are sentences a step's agent follows. `develop` receives the
+`engineering` group, its own two rules, and a `pytest` hook that sends the step
+back to the worker when it fails, instead of stopping for the operator. Each
+rule file is Markdown; its first sentence is shown on the step page.
+
+```markdown
+<!-- rules/python/no-print.md -->
+---
+paths: ["src/**/*.py"]
+check:
+  shell: grep -l 'print(' $WW_STEP_CHANGED_FILES || true
+  assert: [empty]
+---
+Log through the `logging` module; never call `print` in library code.
+
+Scripts under `bin/` may print; they are not library code.
+```
+
+```markdown
+<!-- rules/python/contracts.md -->
+State the observable behaviour being changed and the invariants that must hold.
+```
+
+```yaml
+rules:
+  engineering:
+    rules: [rules/python/]
+    workflows: [task]
+    steps: [develop, refactor]
+
+workflows:
+  - name: task
+    steps:
+      - name: develop
+        description: Implement the change with tests.
+        rules:
+          - Keep the public CLI unchanged.
+          - text: Leave no TODO in the files you change.
+            shell: grep -l TODO $WW_STEP_CHANGED_FILES || true
+            assert: [empty]
+        hooks:
+          before_complete:
+            - argv: [pytest, -q]
+              on_failure: fix
+      - name: refactor
+        description: Simplify what develop wrote.
+      - review: Review the change.
+```
+
+```json
+{ "limits": { "fixes": 3 } }
+```
+
+When a check fails, `complete` exits non-zero and shows which checks failed
+and what they printed; the step stays with its worker. After three rejected
+completions ww stops with `operator_reason: fix_limit`: `next --retry` gives
+the worker another round, `next --force --reason` waives the checks.
+
+The rules without a command, "Keep the public CLI unchanged." and the
+engineering rules, go to a verifier once develop's checks pass. The verifier
+gives a verdict, and a failing one sends develop back like a failed check.
+`discover` and `start` say how many rules have no check yet; the
+`ww-scriptize` skill starts `ww-scriptize-rules`, which builds checks for them
+with the operator, and ww then runs each check for its wording in every later
+step instead of asking a verifier.
+
+## 21. What ww-suggest proposes for a Node project with dev/main and a Jira-like tracker
+
+The shape to expect from `ww-suggest` for a project that integrates on `dev`,
+releases from `main`, references `PROJ-123` keys in its commits, and verifies
+a change with `npm run lint`, `npm run typecheck` and `npm test`. This project
+treats passing all three as an invariant of every code-changing step, so the
+commands are automatic handlers attached to those steps as `before_complete`
+checks (a project that only needs one visible verification uses a command step
+as in example 1). ww runs them once on completion without asking the agent to
+run them. Failures return their output to that step's worker to fix; ww checks
+again when the worker completes. `bugfix` is `hotfix` on another base
+branch, `hotfix` recommends the merge back into `dev`, and the operator keeps
+the review of a feature. The operator's wish for short updates is a mode, not
+a rule; no rule is needed, since every convention here is a command or a
+setting. Applied for the team, the fragment becomes `ww-setup.yaml`:
+
+```yaml
+handlers:
+  - name: lint
+    argv: [npm, run, lint]
+  - name: typecheck
+    argv: [npm, run, typecheck]
+  - name: run-tests
+    argv: [npm, test]
+
+hooks:
+  before_complete:
+    - workflows: [feature, hotfix, bugfix, merge-to-dev]
+      steps: [implement, fix, merge]
+      on_failure: fix
+      handlers:
+        - name: lint
+        - name: typecheck
+        - name: run-tests
+  before_start_workflow:
+    - workflows: [feature, hotfix, bugfix]
+      handlers:
+        - ext/ww/git/handlers:is-git-clean:
+        - ext/ww/git/handlers:start-task-branch:
+  before_complete_workflow:
+    - workflows: [feature, hotfix, bugfix]
+      handlers:
+        - ext/ww/git/handlers:git-commit:
+
+modes:
+  - brief: Keep updates to the operator to a few plain sentences.
+
+workflows:
+  - feature: Implement a ticket from the tracker, up to a tested commit.
+    steps:
+      - investigate: >-
+          Read the ticket and the code it touches; say what changes and what could
+          break.
+      - implement: Implement the change with its tests.
+        artifact_from: investigate
+      - review: Walk the operator through the change and take their review.
+        interactive: true
+
+  - hotfix: Fix a production bug on main for an urgent release.
+    recommended_next_workflow: merge-to-dev
+    steps:
+      - investigate: Find why the bug happens and reproduce it with a failing test.
+      - fix: Fix the bug at its cause.
+        artifact_from: investigate
+
+  - bugfix: Fix a bug on dev, released with the next regular release.
+    inherit: hotfix
+    recommended_next_workflow:
+
+  - merge-to-dev: Merge a hotfix branch back into dev and leave dev passing.
+    steps:
+      - merge: >-
+          Merge the branch the requirements name into dev with `git merge --no-ff`
+          in the primary checkout, resolving every conflict so that both sides' intent
+          survives. Do not push.
+        role: manager
+```
+
+and its `settings` go into `ww.json`:
+
+```json
+{
+  "task_format": "PROJ-{{digit}}",
+  "extensions": {
+    "ww/git": {
+      "commit_format": "{{ww.task.id}}: {{commit_message}}",
+      "separate_branch": true,
+      "base_branches": {"default": "dev", "hotfix": "main"},
+      "branch_name_formats": {
+        "default": "feature/{{ww.task.id}}",
+        "hotfix": "hotfix/{{ww.task.id}}",
+        "bugfix": "bugfix/{{ww.task.id}}"
+      }
+    }
+  }
+}
+```
+
+A smaller project, one `test` script on a single `main` branch, gets one
+lane, the `run-tests` handler and the git settings; worktrees appear only when
+the operator asks for tasks in parallel.