@collective-intelligence/backlog 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,82 @@
1
+ ---
2
+ name: human-backlog-ado
3
+ description: Reference for `ado.py`, the Azure DevOps helper that the Human Backlog skills call. Use when a Human Backlog skill runs `ado.py`, or when `ado.py` stops on the Human Backlog Config or on Azure CLI sign-in.
4
+ ---
5
+
6
+ # Human Backlog helper
7
+
8
+ `scripts/ado.py` is one Python 3 file with no dependencies beyond the standard library. Sibling skills run it as `python3 ../human-backlog-ado/scripts/ado.py <command>` from their own directory and call it `<ado>`. Every command prints JSON on stdout. On a stop it prints `{"error": "..."}` on stderr and exits 1; read the error before you retry.
9
+
10
+ `python3 <ado> --help` and `python3 <ado> <command> --help` list the exact arguments. `--help` needs no config.
11
+
12
+ ## Human Backlog Config
13
+
14
+ The helper resolves each key on its own; the first source with a value wins:
15
+
16
+ 1. The env var in the table.
17
+ 2. `humanBacklog.<key>` in the nearest `.devpunks/settings.json` above the working directory.
18
+ 3. `<key>` in `config.json` beside `ado.py` (an Eject carries this file).
19
+
20
+ | Key | Env var | Value |
21
+ | -------------------- | -------------------------- | --------------------------------------------------------------------------------- |
22
+ | `provider` | `ADO_PROVIDER` | `azure-devops` |
23
+ | `projectUrl` | `ADO_PROJECT_URL` | `https://dev.azure.com/{org}/{project}`; the helper takes org and project from it |
24
+ | `tenant` | `ADO_TENANT` | Entra tenant ID for `az login` |
25
+ | `ratingsPipelineUrl` | `ADO_RATINGS_PIPELINE_URL` | Optional URL of the pipeline that reconciles Feature ratings; `whoami` prints it |
26
+
27
+ A missing `provider`, `projectUrl` or `tenant`, or an invalid value, stops the command with the key name before any network call. Tell the user which key to set and where.
28
+
29
+ ## Azure CLI sign-in
30
+
31
+ The helper gets its token only from `az account get-access-token --tenant <tenant>`. When the Azure CLI is missing or not signed in, the command stops before any network call and the error names the tenant. Ask the user to install the [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) when it is missing, then to run `az login --tenant <tenant>`. Confirm access with `python3 <ado> whoami`.
32
+
33
+ ## Commands
34
+
35
+ | Command | Use |
36
+ | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
37
+ | `whoami` | Signed-in user, org, project and `ratingsPipelineUrl` |
38
+ | `get ID [ID ...]` | Work items with fields as plain text, links and attachments |
39
+ | `backlog [--types ...] [--under ID] [--include-removed] [--chars N]` | Items for matching; `--chars 0` keeps full text |
40
+ | `search TEXT [--types ...]` | Keyword search in title and description |
41
+ | `create --type T --json FILE [--parent ID] [--dry-run]` | Create one item; `--dry-run` asks Azure DevOps to validate without saving |
42
+ | `update ID --json FILE [--expected-rev N] [--dry-run]` | Patch fields with a revision test |
43
+ | `link SOURCE TARGET --type related\|parent\|child [--comment TEXT] [--dry-run]` | Add a link; Related links reconcile Feature ratings |
44
+ | `unlink SOURCE TARGET --type related [--expected-rev N] [--dry-run]` | Remove a Related link |
45
+ | `set-state ID STATE --comment TEXT [--expected-rev N] [--dry-run]` | Move a Business Request to a Human State; see **Human State** |
46
+ | `revision-check ID [--touch ID ...] [--shared-approved ID ...]` | Read-only check of a Business Request revision |
47
+ | `planning-context [--team T] [--iteration I]` | Team calendar, members, iterations and sprint load |
48
+ | `planning-check PLAN.json` | Read-only check of a sprint proposal |
49
+ | `hyperlink ID URL [--comment TEXT]` | Add one Hyperlink relation, such as the back link to a Fog; see **Hyperlinks** |
50
+ | `unhyperlink ID URL` | Remove the Hyperlink relation to URL; see **Hyperlinks** |
51
+ | `comment ID (--text TEXT \| --file FILE) [--dry-run]` | Add a discussion comment |
52
+ | `attach ID --file FILE --receipt JSON [--comment TEXT] [--dry-run]` | Upload and link one evidence file, resumable through the receipt |
53
+ | `sync-ratings [ID ... \| --all] [--dry-run]` | Recompute Feature ratings from linked Business Requests |
54
+ | `apply PLAN.json [--dry-run]` | Create a backlog plan; see `../analyze-business-request/references/plan-format.md` |
55
+ | `doctor` | Read-only check of the config and the process; see **Setup** |
56
+ | `eject --out PATH` | Zip the Human Backlog skills with the config; see **Setup** |
57
+
58
+ Field JSON uses the helper's friendly names (`Title`, `Description`, `AcceptanceCriteria`, `BusinessValue`, `Urgency`, …) or raw reference names. Rich-text fields accept a small Markdown subset (headings, `-` and `1.` lists, `**bold**`, blank-line paragraphs), which the helper converts to HTML.
59
+
60
+ A transport error means the write may have completed. Read the item before you retry.
61
+
62
+ ## Hyperlinks
63
+
64
+ `hyperlink` and `unhyperlink` are safe to retry: an item that already links `URL`, or no longer links it, stays unchanged (`status` `unchanged`, no write). To move a back link to a successor Fog, run `unhyperlink` with the old URL, then `hyperlink` with the new one. Otherwise one revision-tested patch adds or removes the relation (`status` `written`); a concurrent edit makes it stop with exit 1, so read the item and run it again. `get` lists each Hyperlink as `{"url", "comment"}` in `hyperlinks`, beside `relations` (work-item links) and `attachments`. Use `hyperlink` for a back link that you must read back; a comment has neither property.
65
+
66
+ ## Human State
67
+
68
+ A Business Request has one of eight Human States: Received, In analysis, Planned, In progress, On staging, Live, Rejected, Withdrawn. Use these names exactly. Received is the initial state of the type, so `create` sends no State. `set-state` is the only command that changes a Business Request's State; `create` and `update` refuse a State field on a Business Request.
69
+
70
+ ```bash
71
+ python3 <ado> set-state <id> "<Human State>" --comment "<why, in the request's language>"
72
+ ```
73
+
74
+ `set-state` moves forward through Received → In analysis → Planned → In progress → On staging → Live, and to Rejected or Withdrawn from every non-final state. Live, Rejected and Withdrawn are final. The JSON `status` is `written`, `unchanged` (the request is already in that state; nothing is written, exit 0) or `would_write` with `--dry-run`. A backward move, a move out of a final state or an unknown name is refused: exit 1, no write. Report a refusal to the user; it is the answer, not a fault to retry around. A write is one revision-tested patch that sets State and adds `--comment` as one discussion comment. `python3 <ado> set-state --help` lists the exact rules.
75
+
76
+ ## Setup
77
+
78
+ `../setup-human-backlog/SKILL.md` runs both commands; follow it to set up a Human Backlog.
79
+
80
+ `doctor` only reads. It checks `config`, `az`, `project`, `types`, `fields`, `states`, `iterations` and `create` against the process in `../setup-human-backlog/references/process.md`; `create` asks Azure DevOps to validate, without saving, one create per type with only the fields the skills always set, so a process that requires an optional field, such as Requester, fails it. The JSON `status` is `ready` (exit 0) when every check passes; otherwise `blocked` (exit 1), with each check's `pass`, `fail` or `skipped` and every mismatch in `mismatches`. A failing `config`, `az` or `project` check skips the checks after it.
81
+
82
+ `eject --out PATH` writes one zip of the Human Backlog skills installed beside this one, with the resolved config as `human-backlog-ado/scripts/config.json` and a `MANIFEST.json`. `PATH` is a zip file, or an existing directory that receives `human-backlog-skills.zip`. `../setup-human-backlog/references/eject.md` describes the contents.