@collective-intelligence/backlog 0.2.2 → 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.
Files changed (25) hide show
  1. package/README.md +67 -34
  2. package/package.json +2 -2
  3. package/skills/generate-human-backlog-skills/SKILL.md +117 -0
  4. package/skills/generate-human-backlog-skills/references/client-profile.md +51 -0
  5. package/skills/generate-human-backlog-skills/references/eject.md +31 -0
  6. package/skills/{setup-human-backlog → generate-human-backlog-skills}/references/process.md +7 -5
  7. package/skills/{analyze-business-request/SKILL.md → generate-human-backlog-skills/references/templates/analyze-business-request/SKILL.md.tmpl} +14 -8
  8. package/skills/{analyze-business-request → generate-human-backlog-skills/references/templates/analyze-business-request}/references/plan-format.md +3 -3
  9. package/skills/{create-bug/SKILL.md → generate-human-backlog-skills/references/templates/create-bug/SKILL.md.tmpl} +7 -5
  10. package/skills/{create-bug → generate-human-backlog-skills/references/templates/create-bug}/references/azure-operations.md +1 -1
  11. package/skills/{create-business-request/SKILL.md → generate-human-backlog-skills/references/templates/create-business-request/SKILL.md.tmpl} +24 -18
  12. package/skills/{create-business-request → generate-human-backlog-skills/references/templates/create-business-request}/references/example.md +1 -1
  13. package/skills/{create-business-request → generate-human-backlog-skills/references/templates/create-business-request}/references/intake-guide.md +2 -2
  14. package/skills/{human-backlog-ado/SKILL.md → generate-human-backlog-skills/references/templates/human-backlog-ado/SKILL.md.tmpl} +32 -37
  15. package/skills/{plan-sprint/SKILL.md → generate-human-backlog-skills/references/templates/plan-sprint/SKILL.md.tmpl} +6 -4
  16. package/skills/{plan-sprint → generate-human-backlog-skills/references/templates/plan-sprint}/references/assessment-guide.md +1 -1
  17. package/skills/{plan-sprint → generate-human-backlog-skills/references/templates/plan-sprint}/references/operations.md +1 -1
  18. package/skills/{update-business-request/SKILL.md → generate-human-backlog-skills/references/templates/update-business-request/SKILL.md.tmpl} +4 -2
  19. package/skills/{human-backlog-ado → generate-human-backlog-skills}/scripts/ado.py +408 -106
  20. package/skills/generate-human-backlog-skills/scripts/render.py +361 -0
  21. package/skills/setup-human-backlog/SKILL.md +0 -83
  22. package/skills/setup-human-backlog/references/eject.md +0 -26
  23. /package/skills/{create-bug → generate-human-backlog-skills/references/templates/create-bug}/references/examples.md +0 -0
  24. /package/skills/{update-business-request → generate-human-backlog-skills/references/templates/update-business-request}/references/examples.md +0 -0
  25. /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; use analyze-business-request to map an existing Business Request to backlog.
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. The `analyze-business-request` skill maps the request into Epics, Features and PBIs. Technical design and implementation work are outside this skill's scope and are managed separately.
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 handled by `update-business-request` within its lifecycle rules.
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 saved content in the user's language, and keep an existing item's language when you edit it. Talk to the user in their language.
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 `analyze-business-request`.
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, hand off the requested change and confirmed answers to `update-business-request`, 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.
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 `analyze-business-request`; technical design is outside this skill's scope and is managed separately.
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 **1 (minimum)** to **5 (maximum)**.
110
- - **Urgency**: how urgent the requested capability is for the business, from **1 (minimum)** to **5 (maximum)**.
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
- 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. 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.
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 through `update-business-request`, 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 1. 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.
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 1 to 5.
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"`. Later Human States belong to `analyze-business-request`, `plan-sprint`, `update-business-request` and `write-backlog`, through `set-state`. Report the new Business Request's ID and URL and any intentionally unresolved questions. Suggest `analyze-business-request` for subsequent analysis. Existing Business Request revisions belong to `update-business-request`; do not bypass its state and sharing checks with a direct `update`.
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 `analyze-business-request`.
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 1 to 5 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.
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`, numeric integer 1–5, stored in `Custom.BusinessValueScore`.
218
+ **Business Value**: JSON `BusinessValue`, integer {{ratings.min}}–{{ratings.max}}.
213
219
 
214
- **Urgency**: JSON `Urgency`, numeric integer 1–5, stored in `Custom.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: “From 1 (minimum) to 5 (maximum), what values do you give business value and urgency? They are two separate ratings.” The user answers: “Value 4, urgency 3.” Record those numbers without inferring either from the January deadline.
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 analyze-business-request 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.
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 1 (minimum) to 5 (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.
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
- ## Human Backlog Config
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
- The helper resolves each key on its own; the first source with a value wins:
14
+ ## Human Backlog Config
15
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).
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 to set and where.
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, 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.
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 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.
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
- ## Setup
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 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.
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
- `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.
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 two-week sprint, and applies the approved assignment. Use to plan, fill or check a sprint; PBI order stays with the developer.
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 two-week sprint. A developer may complete several Features in sequence but works on one at a time. PBI order and execution belong to the developer.
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 saved content in the user's language, and keep an existing item's language when you edit it. Talk to the user in their language. 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.
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. Two working weeks often mean ten working days, but check 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.
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 cannot take both in a ten-day sprint. 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.
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 for two configured working weeks 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.
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 saved content in the user's language, and keep an existing item's language when you edit it. Talk to the user in their language. Technical design and implementation management are out of scope and handled separately.
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