@collective-intelligence/backlog 0.2.1 → 0.2.3
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.
- package/README.md +67 -34
- package/package.json +2 -2
- package/skills/generate-human-backlog-skills/SKILL.md +117 -0
- package/skills/generate-human-backlog-skills/references/client-profile.md +51 -0
- package/skills/generate-human-backlog-skills/references/eject.md +31 -0
- package/skills/{setup-human-backlog → generate-human-backlog-skills}/references/process.md +7 -5
- package/skills/{analyze-business-request/SKILL.md → generate-human-backlog-skills/references/templates/analyze-business-request/SKILL.md.tmpl} +14 -8
- package/skills/{analyze-business-request → generate-human-backlog-skills/references/templates/analyze-business-request}/references/plan-format.md +3 -3
- package/skills/{create-bug/SKILL.md → generate-human-backlog-skills/references/templates/create-bug/SKILL.md.tmpl} +7 -5
- package/skills/{create-bug → generate-human-backlog-skills/references/templates/create-bug}/references/azure-operations.md +1 -1
- package/skills/{create-business-request/SKILL.md → generate-human-backlog-skills/references/templates/create-business-request/SKILL.md.tmpl} +24 -18
- package/skills/{create-business-request → generate-human-backlog-skills/references/templates/create-business-request}/references/example.md +1 -1
- package/skills/{create-business-request → generate-human-backlog-skills/references/templates/create-business-request}/references/intake-guide.md +2 -2
- package/skills/{human-backlog-ado/SKILL.md → generate-human-backlog-skills/references/templates/human-backlog-ado/SKILL.md.tmpl} +32 -37
- package/skills/{plan-sprint/SKILL.md → generate-human-backlog-skills/references/templates/plan-sprint/SKILL.md.tmpl} +6 -4
- package/skills/{plan-sprint → generate-human-backlog-skills/references/templates/plan-sprint}/references/assessment-guide.md +1 -1
- package/skills/{plan-sprint → generate-human-backlog-skills/references/templates/plan-sprint}/references/operations.md +1 -1
- package/skills/{update-business-request/SKILL.md → generate-human-backlog-skills/references/templates/update-business-request/SKILL.md.tmpl} +4 -2
- package/skills/{human-backlog-ado → generate-human-backlog-skills}/scripts/ado.py +408 -106
- package/skills/generate-human-backlog-skills/scripts/render.py +361 -0
- package/skills/setup-human-backlog/SKILL.md +0 -83
- package/skills/setup-human-backlog/references/eject.md +0 -26
- /package/skills/{create-bug → generate-human-backlog-skills/references/templates/create-bug}/references/examples.md +0 -0
- /package/skills/{update-business-request → generate-human-backlog-skills/references/templates/update-business-request}/references/examples.md +0 -0
- /package/skills/{update-business-request → generate-human-backlog-skills/references/templates/update-business-request}/references/operations.md +0 -0
|
@@ -1,15 +1,17 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: create-business-request
|
|
3
|
-
description: Intake for a new Business Request in the Human Backlog (Azure DevOps). Runs a demanding business interview from a short ask, meeting notes, email or documents, checks duplicate Business Requests, and creates the approved item. Use to capture a new business ask, directly or when another skill hands one over;
|
|
3
|
+
description: Intake for a new Business Request in the {{client.name}} Human Backlog (Azure DevOps). Runs a demanding business interview from a short ask, meeting notes, email or documents, checks duplicate Business Requests, and creates the approved item. Use to capture a new business ask, directly or when another skill hands one over; mapping an existing Business Request to backlog is backlog analysis, a separate step.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Create a Business Request
|
|
7
7
|
|
|
8
|
-
A Business Request records the complete customer request in enough detail that a Product Owner can analyze it without the intake conversation. It uses business language.
|
|
8
|
+
A Business Request records the complete customer request in enough detail that a Product Owner can analyze it without the intake conversation. It uses business language. Backlog analysis later maps the request into Epics, Features and PBIs. Technical design and implementation work are outside this skill's scope and are managed separately.
|
|
9
9
|
|
|
10
|
-
The Business Request captures the request at intake. Later refinements can be recorded directly in Features and PBIs using the PO/developer's knowledge and any offline customer discussions; keeping the Business Request synchronized with those discussions is not required. This does not lower the intake completeness standard. Explicit corrections or revisions of an existing Business Request are
|
|
10
|
+
The Business Request captures the request at intake. Later refinements can be recorded directly in Features and PBIs using the PO/developer's knowledge and any offline customer discussions; keeping the Business Request synchronized with those discussions is not required. This does not lower the intake completeness standard. Explicit corrections or revisions of an existing Business Request are a Business Request revision, with its own lifecycle rules.
|
|
11
11
|
|
|
12
|
-
Write
|
|
12
|
+
Write everything a business user sees in {{language.name}}: your questions and messages, saved item text and comments. Keep an existing item's language when you edit it.
|
|
13
|
+
|
|
14
|
+
Work item types: these instructions say Business Request, Epic, Feature, Product Backlog Item (PBI) and Bug; in this project they are `{{types.businessRequest}}`, `{{types.epic}}`, `{{types.feature}}`, `{{types.productBacklogItem}}` and `{{types.bug}}`. Use the project's names when you talk to the user or write an item.
|
|
13
15
|
|
|
14
16
|
## Intake standard
|
|
15
17
|
|
|
@@ -17,7 +19,7 @@ Your job is to extract and document the business information the PO needs to und
|
|
|
17
19
|
|
|
18
20
|
- The user's sentence sets the scope. Context supplies evidence, not permission to add adjacent requests.
|
|
19
21
|
- Treat the content as claims to clarify, not requirements to accept automatically. Separate confirmed facts, proposals, contradictions and missing decisions. Preserve useful source references in the saved Business Request's Context, including known dates or asset versions. For an existing approval, record what was approved; do not infer approval of other aspects.
|
|
20
|
-
- Stay at Business Request level. Search and compare **only Business Requests**, in every Human State, including Live, Rejected and Withdrawn ones. Do not search, inspect or assess Features, Epics, PBIs, Bugs, implementation or delivery coverage, even if a Business Request links to them. That belongs to
|
|
22
|
+
- Stay at Business Request level. Search and compare **only Business Requests**, in every Human State, including Live, Rejected and Withdrawn ones. Do not search, inspect or assess Features, Epics, PBIs, Bugs, implementation or delivery coverage, even if a Business Request links to them. That belongs to backlog analysis.
|
|
21
23
|
- Strong intake is adaptive: no minimum question count, no fixed questionnaire to recite. Ask only about unresolved decisions, but do not accept an incomplete answer merely because you asked the question.
|
|
22
24
|
- Preserve substantive detail in the saved Business Request. Decisions left only in chat are unavailable to the PO. Use a short summary followed by structured detail, examples and rules; never compress away information just to keep the Business Request short. Do not make the requester write the document: extract and organize their answers.
|
|
23
25
|
- A named decision owner and success criteria are optional supporting information. Record them when supplied or useful; do not run question rounds solely to obtain them. When the customer explicitly requires approval before work can proceed, clarify the approving role, what they approve and what depends on that approval. Expected behavior must still be clear even without formal acceptance criteria.
|
|
@@ -46,7 +48,7 @@ python3 <ado> search "<business terms>" --types br
|
|
|
46
48
|
python3 <ado> get <candidate Business Request ids>
|
|
47
49
|
```
|
|
48
50
|
|
|
49
|
-
Use full Business Request descriptions where summaries are insufficient. Similar words are not enough: compare audience, capability and scope. Show any meaningful overlap and its state. Ask whether to request a revision of the existing Business Request, keep a separate request with an explicit distinction, or stop. For an agreed revision,
|
|
51
|
+
Use full Business Request descriptions where summaries are insufficient. Similar words are not enough: compare audience, capability and scope. Show any meaningful overlap and its state. Ask whether to request a revision of the existing Business Request, keep a separate request with an explicit distinction, or stop. For an agreed revision, end this intake and pass the requested change and confirmed answers to a Business Request revision, which checks lifecycle eligibility and shared impact; do not edit the existing Business Request directly from this intake. Do not silently merge or reopen requests. If access fails, disclose that duplicate checking is incomplete rather than claiming no duplicates exist.
|
|
50
52
|
|
|
51
53
|
**Done when:** the request's elements are extracted, and every candidate duplicate Business Request is compared by meaning or the incomplete duplicate check is disclosed.
|
|
52
54
|
|
|
@@ -96,7 +98,7 @@ A Business Request is ready for normal creation when the relevant business dimen
|
|
|
96
98
|
|
|
97
99
|
Before previewing, read the draft as the PO receiving it without the conversation. For each capability, ask: “What would I still need to ask the business before I can understand and analyze this?” If that question exposes an ambiguity in meaning, information, behavior or rules, return to the user with a targeted question. If two plausible business interpretations remain, show them and ask which is intended. Do not choose the more likely one silently.
|
|
98
100
|
|
|
99
|
-
Record all material answers in the Business Request, including examples and rules discovered during follow-ups. A terse request plus a long, discarded interview is not a complete handoff. Formal success criteria, KPIs and a named decider are not readiness gates. Backlog decomposition remains for
|
|
101
|
+
Record all material answers in the Business Request, including examples and rules discovered during follow-ups. A terse request plus a long, discarded interview is not a complete handoff. Formal success criteria, KPIs and a named decider are not readiness gates. Backlog decomposition remains for backlog analysis; technical design is outside this skill's scope and is managed separately.
|
|
100
102
|
|
|
101
103
|
A specific Target Date is still needed to satisfy the configured Azure field requirement. Treat it as administrative business input, distinguish a desired date from a fixed deadline when relevant, and never imply a delivery commitment. Do not demand an ROI calculation, implementation inventory, detailed UI specification, estimate or sprint plan.
|
|
102
104
|
|
|
@@ -106,14 +108,18 @@ A specific Target Date is still needed to satisfy the configured Azure field req
|
|
|
106
108
|
|
|
107
109
|
For every Business Request, ask the user for two independent ratings and record the confirmed numbers:
|
|
108
110
|
|
|
109
|
-
- **Business Value**: how valuable the requested capability is to the business, from **
|
|
110
|
-
- **Urgency**: how urgent the requested capability is for the business, from **
|
|
111
|
+
- **Business Value**: how valuable the requested capability is to the business, from **{{ratings.min}} (minimum)** to **{{ratings.max}} (maximum)**.
|
|
112
|
+
- **Urgency**: how urgent the requested capability is for the business, from **{{ratings.min}} (minimum)** to **{{ratings.max}} (maximum)**.
|
|
113
|
+
|
|
114
|
+
These are business judgments, not AI estimates. One may be high while the other is low. Do not infer Urgency from Target Date or use Priority as a substitute. Reuse scores already explicitly supplied; if missing, ask both in one concise question, for example:
|
|
115
|
+
|
|
116
|
+
{{slot:ratings-question}}
|
|
111
117
|
|
|
112
|
-
|
|
118
|
+
Include both in the exact field preview. The helper requires both for a new Business Request, including an explicitly incomplete draft; do not invent defaults. Existing Business Requests without scores need a business answer before their linked Features can be scored reliably.
|
|
113
119
|
|
|
114
|
-
During an authorized Business Request revision
|
|
120
|
+
During an authorized Business Request revision, the helper recalculates the separate maxima on linked Features only in New or Planned. Ratings on Committed, In Progress, Resolved, Done or Removed Features stay unchanged. Report any missing linked-Business Request scores or frozen Features returned by the helper; do not silently treat missing scores as {{ratings.min}}. When the Human Backlog Config names a `ratingsPipelineUrl`, that pipeline also reconciles eligible Features on its schedule, covering manual Azure changes. Do not inspect Feature content yourself as part of this creation skill.
|
|
115
121
|
|
|
116
|
-
**Done when:** the user has given both ratings as integers from
|
|
122
|
+
**Done when:** the user has given both ratings as integers from {{ratings.min}} to {{ratings.max}}.
|
|
117
123
|
|
|
118
124
|
### 5. Preview and approve
|
|
119
125
|
|
|
@@ -133,14 +139,14 @@ python3 <ado> create --type br --json /tmp/br.json
|
|
|
133
139
|
python3 <ado> get <new id>
|
|
134
140
|
```
|
|
135
141
|
|
|
136
|
-
Received is the initial Human State of a Business Request, so the new item reads back `"state": "Received"`.
|
|
142
|
+
Received is the initial Human State of a Business Request, so the new item reads back `"state": "Received"`. Backlog analysis, sprint planning, Business Request revision and delivery write the later Human States through `set-state`. Report the new Business Request's ID and URL and any intentionally unresolved questions. Suggest backlog analysis as the next step. An existing Business Request changes only through a Business Request revision; a direct `update` bypasses its state and sharing checks.
|
|
137
143
|
|
|
138
144
|
**Done when:** `get` reads the new Business Request back in Received, and the user has its ID and URL.
|
|
139
145
|
|
|
140
146
|
## What stays out
|
|
141
147
|
|
|
142
148
|
- **Anything outside the topic**, even when the context talks about it.
|
|
143
|
-
- **Implementation inventory and delivery coverage.** Do not investigate the existing product or compare backlog coverage. The current business process, vocabulary or an example may be clarified when necessary to understand the request; record relevant supplied assets in Context. Technical comparison with what exists belongs to
|
|
149
|
+
- **Implementation inventory and delivery coverage.** Do not investigate the existing product or compare backlog coverage. The current business process, vocabulary or an example may be clarified when necessary to understand the request; record relevant supplied assets in Context. Technical comparison with what exists belongs to backlog analysis.
|
|
144
150
|
- **Unconfirmed solution proposals and agent-selected technology.** If someone suggests a solution, capture the need behind it: "maybe Azure AI Search" becomes "Employees find a document by describing it". When it is unclear whether a named technology or platform is a suggestion or a requirement, ask. Preserve confirmed customer constraints in Context, with their reason when available; for example, publication on the customer's existing WordPress site.
|
|
145
151
|
- **Implementation estimates, sprint plans, staffing and agent-designed delivery phases.** Preserve customer-requested deliverables, sequencing and approval conditions; they are part of the request.
|
|
146
152
|
- **Internal codes** (use-case numbers, requirement IDs, slide numbers) in the business narrative. Keep useful source identifiers and references in Context, with enough detail to locate the material and distinguish its version or approval scope.
|
|
@@ -158,9 +164,9 @@ Make the Business Request easy to scan, with a concise summary and enough detail
|
|
|
158
164
|
|
|
159
165
|
## Fields
|
|
160
166
|
|
|
161
|
-
Azure DevOps requires Title, Description, Context and Existing Assets, Target Date, Business Value and Urgency. Existing Business Requests with blank ratings must have both filled on their next save. Fill Requester and Request Date when known (Request Date is the date of the call or email, otherwise today). Collect Business Value and Urgency directly from the user as integers from
|
|
167
|
+
Azure DevOps requires Title, Description, Context and Existing Assets, Target Date, Business Value and Urgency. Existing Business Requests with blank ratings must have both filled on their next save. Fill Requester and Request Date when known (Request Date is the date of the call or email, otherwise today). Collect Business Value and Urgency directly from the user as integers from {{ratings.min}} to {{ratings.max}} before normal creation; never assign them yourself or derive them from Priority or Target Date. Set Priority only if the business said so. Never set Start Date, Iteration, Assigned To or State.
|
|
162
168
|
|
|
163
|
-
Rich-text fields accept a small Markdown subset (`##` headings, `-` and `1.` lists, `**bold**`, blank-line paragraphs). The script converts it to HTML.
|
|
169
|
+
Rich-text fields accept a small Markdown subset (`##` headings, `-` and `1.` lists, `**bold**`, blank-line paragraphs). The script converts it to HTML. Write the section headings of the templates below in {{language.name}}.
|
|
164
170
|
|
|
165
171
|
**Title**: what the business wants, in business words, under about 80 characters, no technology. "Employees find their HR documents in the portal".
|
|
166
172
|
|
|
@@ -209,9 +215,9 @@ If there is nothing, write "Nothing known yet."
|
|
|
209
215
|
- ‹Known source reference and date or asset version; for an approval, what it covers›.
|
|
210
216
|
```
|
|
211
217
|
|
|
212
|
-
**Business Value**: JSON `BusinessValue`,
|
|
218
|
+
**Business Value**: JSON `BusinessValue`, integer {{ratings.min}}–{{ratings.max}}.
|
|
213
219
|
|
|
214
|
-
**Urgency**: JSON `Urgency`,
|
|
220
|
+
**Urgency**: JSON `Urgency`, integer {{ratings.min}}–{{ratings.max}}.
|
|
215
221
|
|
|
216
222
|
**Requester**: the person's email (preferred), or "Display Name <email>". **Request Date** and **Target Date**: `YYYY-MM-DD`.
|
|
217
223
|
|
|
@@ -59,7 +59,7 @@ The source says January but Azure requires a specific Target Date. Ask for it; t
|
|
|
59
59
|
|
|
60
60
|
## Business ratings
|
|
61
61
|
|
|
62
|
-
Ask
|
|
62
|
+
Ask the ratings question from SKILL.md, which names the scale from {{ratings.min}} (minimum) to {{ratings.max}} (maximum) and says the two ratings are separate. The user answers: “Value 4, urgency 3.” Record those numbers without inferring either from the January deadline.
|
|
63
63
|
|
|
64
64
|
## Resulting Business Request preview
|
|
65
65
|
|
|
@@ -59,10 +59,10 @@ Read the draft without relying on chat history:
|
|
|
59
59
|
- Would two reasonable readers infer materially different behavior anywhere?
|
|
60
60
|
- Are substantive answers and examples actually recorded in the Business Request?
|
|
61
61
|
|
|
62
|
-
If a material business ambiguity remains, ask about it. If the only open questions concern implementation or decomposition, hand off to
|
|
62
|
+
If a material business ambiguity remains, ask about it. If the only open questions concern implementation or decomposition, hand off to backlog analysis for backlog mapping; technical design is outside this skill's scope and is managed separately. Do not reopen optional ownership or success measurement just to fill a template. Subsequent refinements and offline customer clarifications can be reflected directly in Features and PBIs without updating the original Business Request.
|
|
63
63
|
|
|
64
64
|
If the user cannot answer or stops, state the precise missing business decisions. Save incomplete work only on an explicit request with those gaps visible and Azure-required fields supplied. Missing optional fields alone does not make a Business Request incomplete.
|
|
65
65
|
|
|
66
66
|
## Business ratings
|
|
67
67
|
|
|
68
|
-
Before creating, collect Business Value and Urgency from the user, each an integer from
|
|
68
|
+
Before creating, collect Business Value and Urgency from the user, each an integer from {{ratings.min}} (minimum) to {{ratings.max}} (maximum). Ask for the two numbers together where practical. These prioritization inputs do not replace the business-detail interview. Do not demand a KPI or ROI to justify them and do not choose scores for the user. A concrete requested date is a separate input from subjective urgency.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
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.
|
|
3
|
+
description: Reference for `ado.py`, the Azure DevOps helper that the {{client.name}} 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
4
|
---
|
|
5
5
|
|
|
6
6
|
# Human Backlog helper
|
|
@@ -9,13 +9,11 @@ description: Reference for `ado.py`, the Azure DevOps helper that the Human Back
|
|
|
9
9
|
|
|
10
10
|
`python3 <ado> --help` and `python3 <ado> <command> --help` list the exact arguments. `--help` needs no config.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Write everything a business user sees in {{language.name}}: your questions and messages, saved item text and comments. Keep an existing item's language when you edit it.
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
## Human Backlog Config
|
|
15
15
|
|
|
16
|
-
|
|
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).
|
|
16
|
+
`scripts/config.json` holds the values that the team that generated these skills proved against the project: `provider`, `projectUrl`, `tenant`, the optional `ratingsPipelineUrl`, the project's names for work item types and fields, the rating scale and the sprint length. An env var overrides its key:
|
|
19
17
|
|
|
20
18
|
| Key | Env var | Value |
|
|
21
19
|
| -------------------- | -------------------------- | --------------------------------------------------------------------------------- |
|
|
@@ -24,7 +22,7 @@ The helper resolves each key on its own; the first source with a value wins:
|
|
|
24
22
|
| `tenant` | `ADO_TENANT` | Entra tenant ID for `az login` |
|
|
25
23
|
| `ratingsPipelineUrl` | `ADO_RATINGS_PIPELINE_URL` | Optional URL of the pipeline that reconciles Feature ratings; `whoami` prints it |
|
|
26
24
|
|
|
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
|
|
25
|
+
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 is wrong, and to ask the team that generated these skills for a corrected zip.
|
|
28
26
|
|
|
29
27
|
## Azure CLI sign-in
|
|
30
28
|
|
|
@@ -32,36 +30,35 @@ The helper gets its token only from `az account get-access-token --tenant <tenan
|
|
|
32
30
|
|
|
33
31
|
## Commands
|
|
34
32
|
|
|
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
|
|
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;
|
|
55
|
-
| `doctor` | Read-only check of the config and the process; see **
|
|
56
|
-
|
|
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.
|
|
33
|
+
| Command | Use |
|
|
34
|
+
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
|
|
35
|
+
| `whoami` | Signed-in user, org, project and `ratingsPipelineUrl` |
|
|
36
|
+
| `get ID [ID ...]` | Work items with fields as plain text, links and attachments |
|
|
37
|
+
| `backlog [--types ...] [--under ID] [--include-removed] [--chars N]` | Items for matching; `--chars 0` keeps full text |
|
|
38
|
+
| `search TEXT [--types ...]` | Keyword search in title and description |
|
|
39
|
+
| `create --type T --json FILE [--parent ID] [--dry-run]` | Create one item; `--dry-run` asks Azure DevOps to validate without saving |
|
|
40
|
+
| `update ID --json FILE [--expected-rev N] [--dry-run]` | Patch fields with a revision test |
|
|
41
|
+
| `link SOURCE TARGET --type related\|parent\|child [--comment TEXT] [--dry-run]` | Add a link; Related links reconcile Feature ratings |
|
|
42
|
+
| `unlink SOURCE TARGET --type related [--expected-rev N] [--dry-run]` | Remove a Related link |
|
|
43
|
+
| `set-state ID STATE --comment TEXT [--expected-rev N] [--dry-run]` | Move a Business Request to a Human State; see **Human State** |
|
|
44
|
+
| `revision-check ID [--touch ID ...] [--shared-approved ID ...]` | Read-only check of a Business Request revision |
|
|
45
|
+
| `planning-context [--team T] [--iteration I]` | Team calendar, members, iterations and sprint load |
|
|
46
|
+
| `planning-check PLAN.json` | Read-only check of a sprint proposal |
|
|
47
|
+
| `hyperlink ID URL [--comment TEXT]` | Add one Hyperlink relation; see **Hyperlinks** |
|
|
48
|
+
| `unhyperlink ID URL` | Remove the Hyperlink relation to URL; see **Hyperlinks** |
|
|
49
|
+
| `comment ID (--text TEXT \| --file FILE) [--dry-run]` | Add a discussion comment |
|
|
50
|
+
| `attach ID --file FILE --receipt JSON [--comment TEXT] [--dry-run]` | Upload and link one evidence file, resumable through the receipt |
|
|
51
|
+
| `sync-ratings [ID ... \| --all] [--dry-run]` | Recompute Feature ratings from linked Business Requests |
|
|
52
|
+
| `apply PLAN.json [--dry-run]` | Create a backlog plan; the calling skill documents the plan format |
|
|
53
|
+
| `doctor` | Read-only check of the config and the Azure DevOps process; see **Doctor** |
|
|
54
|
+
|
|
55
|
+
`--type` and `--types` take the aliases `br`, `epic`, `feature`, `pbi` and `bug`; `config.json` maps them to this project's work item types. Field JSON uses the helper's friendly names (`Title`, `Description`, `AcceptanceCriteria`, `BusinessValue`, `Urgency`, …), which `config.json` maps to this project's fields, 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
56
|
|
|
60
57
|
A transport error means the write may have completed. Read the item before you retry.
|
|
61
58
|
|
|
62
59
|
## Hyperlinks
|
|
63
60
|
|
|
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
|
|
61
|
+
`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, 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
62
|
|
|
66
63
|
## Human State
|
|
67
64
|
|
|
@@ -73,10 +70,8 @@ python3 <ado> set-state <id> "<Human State>" --comment "<why, in the request's l
|
|
|
73
70
|
|
|
74
71
|
`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
72
|
|
|
76
|
-
##
|
|
77
|
-
|
|
78
|
-
`../setup-human-backlog/SKILL.md` runs both commands; follow it to set up a Human Backlog.
|
|
73
|
+
## Doctor
|
|
79
74
|
|
|
80
|
-
`doctor` only reads. It checks `config`, `az`, `project`, `types`, `fields`, `states`, `iterations` and `create` against the
|
|
75
|
+
`doctor` only reads. It checks `config`, `az`, `project`, `types`, `fields`, `states`, `iterations` and `create` against the Human Backlog process; `create` asks Azure DevOps to validate, without saving, one create per type with only the fields the skills always set. 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
76
|
|
|
82
|
-
`
|
|
77
|
+
On `blocked`, fix an `az` mismatch with the sign-in above. For every other mismatch, show it to the user and tell them to send it to the team that generated these skills: that team owns the process and the config.
|
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: plan-sprint
|
|
3
|
-
description: Sprint planning for the Human Backlog in Azure DevOps. Asks how many developers are available, assesses urgent Features from their full scope, proposes a sequence of whole Features per developer that fits one
|
|
3
|
+
description: Sprint planning for the {{client.name}} Human Backlog in Azure DevOps. Asks how many developers are available, assesses urgent Features from their full scope, proposes a sequence of whole Features per developer that fits one sprint of {{sprint.lengthDays}} days, and applies the approved assignment. Use to plan, fill or check a sprint; PBI order stays with the developer.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Plan a Sprint
|
|
7
7
|
|
|
8
|
-
Help the operator choose a realistic sprint package before changing Azure. The team plans together; each Feature is assigned to one developer and must fit entirely within one
|
|
8
|
+
Help the operator choose a realistic sprint package before changing Azure. The team plans together; each Feature is assigned to one developer and must fit entirely within one sprint of {{sprint.lengthDays}} days. A developer may complete several Features in sequence but works on one at a time. PBI order and execution belong to the developer.
|
|
9
9
|
|
|
10
|
-
Write
|
|
10
|
+
Write everything a business user sees in {{language.name}}: your questions and messages, saved item text and comments. Keep an existing item's language when you edit it. Technical design and implementation management are out of scope and handled separately. A planning assessment concerns scope and feasibility; it does not prescribe architecture or create technical tasks.
|
|
11
|
+
|
|
12
|
+
Work item types: these instructions say Business Request, Epic, Feature, Product Backlog Item (PBI) and Bug; in this project they are `{{types.businessRequest}}`, `{{types.epic}}`, `{{types.feature}}`, `{{types.productBacklogItem}}` and `{{types.bug}}`. Use the project's names when you talk to the user or write an item.
|
|
11
13
|
|
|
12
14
|
## 1. Establish the sprint and available developers
|
|
13
15
|
|
|
@@ -23,7 +25,7 @@ python3 <ado> planning-context --team "<team>"
|
|
|
23
25
|
python3 <ado> planning-context --team "<team>" --iteration "<sprint ID or path>"
|
|
24
26
|
```
|
|
25
27
|
|
|
26
|
-
Use actual iteration dates and paths.
|
|
28
|
+
Use actual iteration dates and paths. A sprint spans {{sprint.lengthDays}} calendar days; count its working days from the configured workweek. For a sprint already underway, use the remaining days. Subtract known absences and other commitments without counting the same deduction twice. The helper does not infer public holidays or individual leave; confirm relevant exceptions with the operator.
|
|
27
29
|
|
|
28
30
|
If only a headcount is known, provisional developer slots are acceptable for discussion. Resolve them to actual member identities before applying assignments. If multiple teams or sprints are plausible, clarify the target. Do not invent identities or iteration paths. This workflow assigns work to configured sprints; if the needed sprint is missing or undated, settle its calendar setup before applying a plan.
|
|
29
31
|
|
|
@@ -38,7 +38,7 @@ Do not infer database changes, libraries, code components or an implementation b
|
|
|
38
38
|
|
|
39
39
|
If three developers each have ten net days, the aggregate budget is thirty developer-days. Each individual sequence must still fit ten days. A twelve-day Feature does not fit simply because the team has unused aggregate capacity.
|
|
40
40
|
|
|
41
|
-
If two Features need six days each, one developer
|
|
41
|
+
If two Features need six days each, one developer with ten net days cannot take both. If the second depends on approval of the first, placing them on two developers does not automatically make them fit either. Check elapsed sequence and approval timing, not just sums.
|
|
42
42
|
|
|
43
43
|
Known absence dates matter to dependencies. A developer available only in the second week cannot provide a first-week prerequisite even if the numerical budget looks adequate. The operator must review these calendar effects; the helper checks numerical budgets, not a complete dated schedule.
|
|
44
44
|
|
|
@@ -12,7 +12,7 @@ python3 <ado> planning-context --team "<team>" --iteration "<actual iteration ID
|
|
|
12
12
|
|
|
13
13
|
If the project has several teams, the first call returns choices. The selected team's context contains member identities, working weekdays and configured iterations. Selecting an iteration also returns the existing Feature/Bug load for that project iteration. It is not a declaration that every member is available or that every work item belongs to the participating developers.
|
|
14
14
|
|
|
15
|
-
The helper reads dates as date-only values, without shifting UTC-midnight dates into another day. It checks
|
|
15
|
+
The helper reads dates as date-only values, without shifting UTC-midnight dates into another day. It checks the iteration against the sprint length of {{sprint.lengthDays}} days and rejects past iterations for normal planning. For a current sprint, only remaining working days are available. Public holidays, individual leave and other commitments must be reflected in the operator-confirmed availability and calendar review.
|
|
16
16
|
|
|
17
17
|
## Temporary proposal
|
|
18
18
|
|
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: update-business-request
|
|
3
|
-
description: Revision of an existing Business Request and its uncommitted Human Backlog Features and PBIs in Azure DevOps. Free edit of a Received Business Request without linked backlog, or cascade through an In analysis or Planned one while every linked Feature is New or Planned; shared Features need explicit user feedback, and every other case is blocked before any write. Marks a Business Request Rejected or Withdrawn when the user asks for that state. Use to correct, expand or reduce an existing Business Request; use create-business-request for a new ask and analyze-business-request to map one without changing it.
|
|
3
|
+
description: Revision of an existing Business Request and its uncommitted {{client.name}} Human Backlog Features and PBIs in Azure DevOps. Free edit of a Received Business Request without linked backlog, or cascade through an In analysis or Planned one while every linked Feature is New or Planned; shared Features need explicit user feedback, and every other case is blocked before any write. Marks a Business Request Rejected or Withdrawn when the user asks for that state. Use to correct, expand or reduce an existing Business Request; use create-business-request for a new ask and analyze-business-request to map one without changing it.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Update a Business Request
|
|
7
7
|
|
|
8
8
|
Revise an existing request and, where allowed, keep its Features and PBIs consistent with the revised scope. This is the explicit revision workflow; `analyze-business-request` continues to treat Business Request content as immutable.
|
|
9
9
|
|
|
10
|
-
Write
|
|
10
|
+
Write everything a business user sees in {{language.name}}: your questions and messages, saved item text and comments. Keep an existing item's language when you edit it. Technical design and implementation management are out of scope and handled separately.
|
|
11
|
+
|
|
12
|
+
Work item types: these instructions say Business Request, Epic, Feature, Product Backlog Item (PBI) and Bug; in this project they are `{{types.businessRequest}}`, `{{types.epic}}`, `{{types.feature}}`, `{{types.productBacklogItem}}` and `{{types.bug}}`. Use the project's names when you talk to the user or write an item.
|
|
11
13
|
|
|
12
14
|
## Two supported paths
|
|
13
15
|
|