@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.
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
package/README.md CHANGED
@@ -1,46 +1,72 @@
1
1
  # @collective-intelligence/backlog
2
2
 
3
- Agent skills for a Human Backlog: the Azure DevOps project where non-technical
4
- client stakeholders ask for work and follow it. The skills ship as plain
5
- folders under `skills/`. Install them beside each other, because each skill
6
- calls the helper as `../human-backlog-ado/scripts/ado.py`.
3
+ One agent skill, `generate-human-backlog-skills`, that generates a client's
4
+ Human Backlog skills: the skills that non-technical client stakeholders use to
5
+ ask for work in an Azure DevOps project and follow it. For one client, the
6
+ generator interviews the team, scans the live project read-only, renders a
7
+ Client Skill Set from its Skill Templates, proves it with `doctor` and Ejects
8
+ it as one zip for the client.
7
9
 
8
10
  ## Install
9
11
 
10
12
  In a Harness Intelligence repo that depends on the Collective Intelligence SDK,
11
- `hi update` installs the seven skills through the `ci-solutions` Pack.
13
+ `hi update` installs the generator through the `ci-solutions` Pack.
12
14
 
13
- Anywhere else, install the package and copy its skill folders into your agent's
15
+ Anywhere else, install the package and copy the skill folder into your agent's
14
16
  skills directory:
15
17
 
16
18
  ```sh
17
19
  npm install @collective-intelligence/backlog
18
- cp -R node_modules/@collective-intelligence/backlog/skills/* .agents/skills/
20
+ cp -R node_modules/@collective-intelligence/backlog/skills/generate-human-backlog-skills .agents/skills/
19
21
  ```
20
22
 
21
- The skills need Python 3 and the Azure CLI.
23
+ The generator needs Python 3 and the Azure CLI. It keeps its answers in
24
+ `.devpunks/settings.json`, so it runs in a Harness Intelligence repo.
22
25
 
23
- ## Skills
26
+ ## Layout
27
+
28
+ ```
29
+ skills/generate-human-backlog-skills/
30
+ SKILL.md the generator
31
+ scripts/ado.py Azure DevOps helper; a Client Skill Set gets a copy
32
+ scripts/render.py renders and checks a Client Skill Set
33
+ references/process.md the Azure DevOps process the team creates by hand
34
+ references/client-profile.md Client Profile schema and interview
35
+ references/eject.md zip contents and client install
36
+ references/templates/<skill>/ one Skill Template: SKILL.md.tmpl and its references
37
+ ```
38
+
39
+ The generator is the only `SKILL.md` in the package, so the repository's agents
40
+ never load a client skill.
41
+
42
+ ## Skill Templates
24
43
 
25
44
  | Skill | Use |
26
45
  | -------------------------- | ---------------------------------------------------------------- |
27
46
  | `create-business-request` | Interview the business and create a new Business Request |
28
47
  | `analyze-business-request` | Map a Business Request to Epics, Features and PBIs |
29
48
  | `update-business-request` | Revise a Business Request and its uncommitted backlog |
30
- | `plan-sprint` | Plan a two-week sprint of whole Features per developer |
49
+ | `plan-sprint` | Plan one sprint of whole Features per developer |
31
50
  | `create-bug` | Turn a business user's problem report into a Bug |
32
- | `setup-human-backlog` | Write and prove the Human Backlog Config; Eject a client zip |
33
- | `human-backlog-ado` | Reference for `scripts/ado.py`, the helper the other skills call |
51
+ | `human-backlog-ado` | Reference for `scripts/ado.py`; every Client Skill Set gets it |
34
52
 
35
- ## Human Backlog Config
53
+ A Client Skill Set holds the selected skills, the skills they hand work to, and
54
+ `human-backlog-ado`. Agent instructions stay English; everything a business
55
+ user sees is in the client's language.
36
56
 
37
- `ado.py` reads four values. For each value the first source wins:
57
+ ## Human Backlog Config and Client Profile
58
+
59
+ `ado.py` reads four Config values. For each value the first source wins:
38
60
 
39
61
  1. the `ADO_*` env var: `ADO_PROVIDER`, `ADO_PROJECT_URL`, `ADO_TENANT` and
40
62
  `ADO_RATINGS_PIPELINE_URL`;
41
63
  2. `humanBacklog` in the nearest `.devpunks/settings.json` above the working
42
64
  directory;
43
- 3. `config.json` beside `ado.py`, which an Eject writes.
65
+ 3. `config.json` beside `ado.py`, which a Client Skill Set carries.
66
+
67
+ The Client Profile sits beside the Config as `humanBacklog.profile`: client
68
+ name, language, selected skills, type and field mappings, rating scale and
69
+ sprint length. `references/client-profile.md` holds its schema.
44
70
 
45
71
  ```json
46
72
  {
@@ -48,13 +74,12 @@ The skills need Python 3 and the Azure CLI.
48
74
  "provider": "azure-devops",
49
75
  "projectUrl": "https://dev.azure.com/<org>/<project>",
50
76
  "tenant": "<Entra tenant ID>",
51
- "ratingsPipelineUrl": "<optional pipeline URL>"
77
+ "ratingsPipelineUrl": "<optional pipeline URL>",
78
+ "profile": { "client": { "name": "<client>" }, "language": { "code": "it", "name": "Italian" }, "skills": ["create-business-request"] }
52
79
  }
53
80
  }
54
81
  ```
55
82
 
56
- `config.json` holds the same keys without the `humanBacklog` wrapper.
57
-
58
83
  ## Sign in
59
84
 
60
85
  `ado.py` gets its token only from the Azure CLI, for the configured tenant.
@@ -62,23 +87,31 @@ Sign in once per machine:
62
87
 
63
88
  ```sh
64
89
  az login --tenant <tenant>
65
- python3 skills/human-backlog-ado/scripts/ado.py whoami
90
+ python3 skills/generate-human-backlog-skills/scripts/ado.py whoami
66
91
  ```
67
92
 
68
- ## Set up and Eject
69
-
70
- Run the `setup-human-backlog` skill once per project. It interviews for the
71
- Human Backlog Config, writes `humanBacklog` into `.devpunks/settings.json` and
72
- runs the read-only `ado.py doctor`. `doctor` reports `ready` when the config,
73
- the sign-in, the project, the work-item types, fields, states, iterations and
74
- one `validateOnly` create per type all pass; otherwise `blocked` with every
75
- mismatch. The team creates the Azure DevOps process by hand from
76
- `skills/setup-human-backlog/references/process.md`.
77
-
78
- On request, the skill runs `ado.py eject --out PATH`: one zip of the seven
79
- skills, the resolved config as `human-backlog-ado/scripts/config.json` and a
80
- `MANIFEST.json` with the package name, a skill-tree sha256, a config sha256 and
81
- the date. A client runs the zip outside Harness Intelligence.
93
+ ## Generate and Eject
94
+
95
+ The generator runs these commands from its own folder:
96
+
97
+ - `ado.py doctor` and `ado.py scan` read the live project. `doctor` reports
98
+ `ready` when the config, the sign-in, the project, the work item types,
99
+ fields, states, iterations and one `validateOnly` create per type all pass;
100
+ otherwise `blocked` with every mismatch. `scan` lists the project's types
101
+ with their fields and states, and its iterations. The team creates the Azure
102
+ DevOps process by hand from `references/process.md`.
103
+ - `render.py render` fills the Skill Templates from `humanBacklog` into a new
104
+ folder outside the repository and reports the free-text slots the agent fills
105
+ in the client's language. `render.py check DIR` refuses a placeholder left, an
106
+ invalid `SKILL.md`, a missing dependency, `human-backlog-ado`, `config.json`
107
+ or `README.md`.
108
+ - `ado.py eject --from DIR --out PATH` refuses unless `check` passes and
109
+ `doctor` is `ready`, then writes one deterministic zip: every file of `DIR`
110
+ and a `MANIFEST.json` with the package name, a template-tree sha256, a
111
+ skill-tree sha256, a config sha256, a Client Profile sha256 and the date.
112
+
113
+ A template update reaches a client only through a new zip that the team
114
+ regenerates from the saved Client Profile.
82
115
 
83
116
  ## Human States
84
117
 
@@ -96,7 +129,7 @@ Rejected and Withdrawn final, and writes nothing when the state is already set.
96
129
  | Withdrawn | a person, or `update-business-request` on request |
97
130
 
98
131
  Harness Intelligence `write-backlog` writes In progress, On staging and Live
99
- from delivery evidence.
132
+ from delivery evidence, through the generator's `scripts/ado.py`.
100
133
 
101
134
  ## Test
102
135
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@collective-intelligence/backlog",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
4
4
  "description": "Human Backlog agent skills and the ado.py Azure DevOps helper: Business Request intake, analysis and revision, sprint planning and Bug intake.",
5
5
  "files": [
6
6
  "README.md",
@@ -18,5 +18,5 @@
18
18
  "publishConfig": {
19
19
  "access": "public"
20
20
  },
21
- "gitHead": "a2aa507323bc6d3ce0ef6d3e460f28573ef40dd8"
21
+ "gitHead": "f22aba0738243e5de0e21c3725e5235fa104963b"
22
22
  }
@@ -0,0 +1,117 @@
1
+ ---
2
+ name: generate-human-backlog-skills
3
+ description: Generate one client's Human Backlog skills (a Client Skill Set) for its Azure DevOps project from Skill Templates, prove them against the live project, and Eject them as one zip. Use when a team sets up a client's Human Backlog, generates or regenerates a client's Human Backlog skills, or Ejects them as a zip.
4
+ ---
5
+
6
+ # Generate Human Backlog skills
7
+
8
+ Build one client's Client Skill Set from the Skill Templates in `references/templates/`, prove it against the client's live Azure DevOps project, and Eject it as one zip that the team sends to the client. This skill's folder is the base directory of every command below: run the helper as `python3 scripts/ado.py <command>` and the renderer as `python3 scripts/render.py <command>`.
9
+
10
+ The Client Skill Set exists only in a rendered folder outside the repository and in the zip. This skill never installs the client skills into the repository, so the repository's agents never load them.
11
+
12
+ The team owns the Human Backlog process. It creates the process once, by hand, in the Azure DevOps organization settings, from `references/process.md`. `doctor` and `scan` only read.
13
+
14
+ ## Regenerate
15
+
16
+ A saved `humanBacklog.profile` in the nearest `.devpunks/settings.json` means an earlier generation exists. Regenerate after a template update or a changed answer: in steps 1 and 3, show the saved values and change only what the team names; run every other step in full. The new zip's `MANIFEST.json` names the template version in `templateTreeSha256`.
17
+
18
+ ## 1. Interview for the Human Backlog Config
19
+
20
+ Ask for the values you do not have yet:
21
+
22
+ - `projectUrl`: `https://dev.azure.com/{org}/{project}`.
23
+ - `tenant`: the Entra tenant ID (a GUID) that the client's users sign in to.
24
+ - `ratingsPipelineUrl`: optional URL of the pipeline that reconciles Feature ratings.
25
+
26
+ `provider` is always `azure-devops`. Set these keys under `humanBacklog` in the nearest `.devpunks/settings.json` above the working directory, and keep every other key and value in that file as it is. When the repository has no `.devpunks/settings.json`, stop: this skill keeps the Config and the Client Profile there. An `ADO_*` env var wins over the file; when one is set, tell the user its value replaces the one you wrote.
27
+
28
+ **Done when:** `humanBacklog` holds `provider`, `projectUrl` in that form, `tenant` as a GUID, and a `ratingsPipelineUrl` or the user's answer that there is none, and every other settings key is unchanged.
29
+
30
+ ## 2. Compare the live project with the process
31
+
32
+ ```bash
33
+ python3 scripts/ado.py doctor
34
+ python3 scripts/ado.py scan
35
+ ```
36
+
37
+ `doctor` checks, in order: `config`, `az` (signed in for the tenant), `project` (reachable), `types`, `fields`, `states`, `iterations` and `create` (a `validateOnly` create per type, which saves nothing). A failing `config`, `az` or `project` check marks the checks after it `skipped`. `scan` returns the project's work item types with their fields and states, and its iterations, as JSON. Fix a failing `config` or `project` check with the step 7 table, then run this step again.
38
+
39
+ Sort every difference from `references/process.md` into one of three outcomes:
40
+
41
+ - **Sign-in blocked** (`az` fails): report the exact `az login --tenant <tenant>` with the tenant from `humanBacklog`, so the person runs it on a machine that may sign in. Stop; this run makes no Eject.
42
+ - **Different name**: the scan holds the part under another name, and the team confirms it is the same type or field. Record the mapping for step 3. Before the Client Profile exists, `doctor` reports such a part as a mismatch; step 7 proves the mapping.
43
+ - **Missing**: a type, a field, one of the eight Human States or a parent link that the process needs is absent. Stop, and list exactly what the team must add, each with its row from `references/process.md`. After the team adds it, run this step again.
44
+
45
+ Human States have no mapping: a Business Request type whose states carry other names is missing Human States.
46
+
47
+ **Done when:** `config`, `az` and `project` pass, and every type, field and Human State of `references/process.md` appears in the scan under its own name or under a mapping the team confirmed; or you stopped with the `az login` command or with the list of parts the team must add.
48
+
49
+ ## 3. Interview for the Client Profile
50
+
51
+ Interview the team for the Client Profile with the scan in hand: client name, language, skills with the skills they bring, type and field mappings from step 2, rating scale and sprint length. Read `references/client-profile.md` for the schema, the defaults and the question for each key. Save the answers as `humanBacklog.profile`.
52
+
53
+ **Done when:** `humanBacklog.profile` holds `client.name`, `language.code`, `language.name` and a non-empty `skills`, every mapping from step 2, and a confirmed value or the default for `ratings` and `sprint`, and every other settings key is unchanged.
54
+
55
+ ## 4. Render the Client Skill Set
56
+
57
+ ```bash
58
+ python3 scripts/render.py render
59
+ ```
60
+
61
+ `render` fills the structured values from `humanBacklog` and writes the Client Skill Set to a new folder outside the repository. It prints `out` (the folder), `skills` (every rendered skill, including the ones a selection brings and `human-backlog-ado`) and `slots` (each `file` with an agent `slot` left to fill). When it refuses a profile key, correct that key in step 3 and render again. Show the team the `skills` list.
62
+
63
+ **Done when:** you have the `render` JSON, and the team has seen its `skills` list.
64
+
65
+ ## 5. Fill the slots
66
+
67
+ Each reported slot is one line `{{slot:<name>}}` in the rendered `file`. Replace that whole line with the content in the table, written in the Client Profile's `language.name`, using the project's type names from `types` and the rating scale from `ratings`. Write only the slots that `render` reported, and leave every other line of the file as it is.
68
+
69
+ | Slot | Template file | Content |
70
+ | ------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
71
+ | `ratings-question` | `create-business-request/SKILL.md` | One `>` quoted question that asks for Business Value and Urgency together, names the scale with its minimum and maximum, and says the two ratings are independent. |
72
+ | `coverage-comments` | `analyze-business-request/SKILL.md` | Two `-` list items, each a Related link comment in code format: one for a new Feature (`Realizes <Business Request type> #123: ` then the needs it covers, in words), one for an existing Feature (`Already covers <Business Request type> #123: ` then the need and the Feature's state). |
73
+ | `recording-request` | `create-bug/SKILL.md` | One `>` quoted request to record a short screen video while reproducing the problem and attach it in the chat: where to start, what to do, what happens, and optionally what the person expected. |
74
+ | `no-parent-message` | `create-bug/SKILL.md` | One `>` quoted ready-to-copy message to the developer: the Bug ID `#123` and `‹URL›` as placeholders, that it has no parent Feature because no reliable match was found, and the request to link it to the correct Feature. |
75
+
76
+ **Done when:** every slot in the `render` JSON has its content, and no line `{{slot:` remains in the rendered folder.
77
+
78
+ ## 6. Check the rendered folder
79
+
80
+ ```bash
81
+ python3 scripts/render.py check <out>
82
+ ```
83
+
84
+ `check` prints `{"status":"ok"}`, or exits 1 with a JSON list of every problem: a `{{` left, a `SKILL.md` whose `name` differs from its folder or that has no `description`, a description that is not valid YAML, a missing dependency, a missing `human-backlog-ado`, `config.json`, `README.md` or `RENDER.json`. Fix a slot you left or broke in step 5. For any other problem, render into a new folder from step 4; when the problem repeats, report it as a template defect of this package.
85
+
86
+ **Done when:** `check` prints `{"status":"ok"}`.
87
+
88
+ ## 7. Prove the project is ready
89
+
90
+ ```bash
91
+ python3 scripts/ado.py doctor
92
+ ```
93
+
94
+ `doctor` now reads the mappings from `humanBacklog.profile`. The JSON `status` is `ready` (exit 0) only when every check passes; otherwise it is `blocked` (exit 1) with every mismatch in `mismatches`. Show every mismatch with the fix for its check, and run `doctor` again after the fix:
95
+
96
+ | Check | Fix |
97
+ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
98
+ | `config` | Correct the key that the mismatch names in step 1. |
99
+ | `az` | Report `az login --tenant <tenant>` and stop, as in step 2. The run makes no Eject. |
100
+ | `project` | Check `projectUrl` and that the signed-in user can open the project. |
101
+ | `types`, `fields`, `states` | A wrong mapping: correct it in step 3 and render again from step 4. A missing part: the team adds it by hand from `references/process.md`. |
102
+ | `iterations` | The team adds sprint iterations to the project's default team. |
103
+ | `create` | The process requires a field that the skills may leave empty; the team makes that field optional, as `references/process.md` describes. |
104
+
105
+ **Done when:** `doctor` reports `ready`, or you stopped at a failing `az` check with the `az login` command.
106
+
107
+ ## 8. Eject
108
+
109
+ Ask the user for a zip path outside the repository; the zip is never committed. Then run:
110
+
111
+ ```bash
112
+ python3 scripts/ado.py eject --from <out> --out <path>
113
+ ```
114
+
115
+ `eject` repeats the `check` rules and `doctor`, and refuses unless both pass and `<out>` was rendered from the saved Client Profile. The zip holds every file of `<out>`, with `MANIFEST.json` in place of `RENDER.json`. Report the zip path and the MANIFEST values `templateTreeSha256`, `skillTreeSha256`, `configSha256`, `profileSha256` and `date` from the JSON. Read `references/eject.md` when the user asks what the zip holds or how the client installs it. After the zip exists, remove the rendered folder `<out>`.
116
+
117
+ **Done when:** the user has the zip path and the five MANIFEST values, and `<out>` is removed.
@@ -0,0 +1,51 @@
1
+ # Client Profile
2
+
3
+ The Client Profile holds the answers of one generation. It sits at `humanBacklog.profile` in the nearest `.devpunks/settings.json`, beside the Human Backlog Config keys. One repository has at most one Client Profile. `render.py render` validates it and refuses an unknown key or a missing required key, naming the key.
4
+
5
+ ```json
6
+ {
7
+ "humanBacklog": {
8
+ "provider": "azure-devops",
9
+ "projectUrl": "https://dev.azure.com/<org>/<project>",
10
+ "tenant": "<tenant GUID>",
11
+ "profile": {
12
+ "client": { "name": "Emera" },
13
+ "language": { "code": "it", "name": "Italian" },
14
+ "skills": ["create-business-request", "analyze-business-request"],
15
+ "types": { "businessRequest": "Business Request", "epic": "Epic", "feature": "Feature",
16
+ "productBacklogItem": "Product Backlog Item", "bug": "Bug" },
17
+ "fields": { "Requester": "Custom.Requester" },
18
+ "ratings": { "min": 1, "max": 5 },
19
+ "sprint": { "lengthDays": 14 }
20
+ }
21
+ }
22
+ }
23
+ ```
24
+
25
+ ## Keys
26
+
27
+ | Key | Required | Value | Default |
28
+ | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
29
+ | `client.name` | yes | The client organization's name as its business users write it | none |
30
+ | `language.code` | yes | ISO 639-1 code of the language the business users read and write, for example `it` | none |
31
+ | `language.name` | yes | English name of that language, for example `Italian`; the templates say "write in `<name>`" | none |
32
+ | `skills` | yes | Non-empty list of client skills: `create-business-request`, `analyze-business-request`, `update-business-request`, `plan-sprint`, `create-bug` | none |
33
+ | `types.<key>` | no | The project's name for each work item type: `businessRequest`, `epic`, `feature`, `productBacklogItem`, `bug` | the canonical name above |
34
+ | `fields.<name>` | no | Azure DevOps reference name for a field the project names differently; `<name>` is a name from the **Name in the skills** column of [`process.md`](process.md). List only the fields that differ. | the `process.md` reference |
35
+ | `ratings.min`/`max` | no | Integer bounds of the Business Value and Urgency scale | 1 and 5 |
36
+ | `sprint.lengthDays` | no | Calendar days of one sprint, in whole weeks: 7, 14, 21 or 28 | 14 |
37
+
38
+ `human-backlog-ado` is never in `skills`: every Client Skill Set gets it. A selected skill brings every skill it hands work to; `render.py render` lists the full set in its `skills` output. Human States have no key: the eight states and their order are fixed.
39
+
40
+ ## Interview
41
+
42
+ Ask the team, one topic per round, and reuse every answer the step 2 scan already gives. Propose a value from the scan where it has one, and let the team confirm or correct it.
43
+
44
+ 1. **Client name.** How the client's business users name their organization.
45
+ 2. **Language.** The one language the client's business users read and write. Every question, message, saved item text and comment in the Client Skill Set uses it; the agent instructions stay English.
46
+ 3. **Skills.** Which work the client's people do with their agent: new Business Requests (`create-business-request`), mapping them to backlog (`analyze-business-request`), revising them (`update-business-request`), sprint planning (`plan-sprint`), Bug reports (`create-bug`). Tell the team that a skill brings the skills it hands work to; the render in step 4 shows the full set.
47
+ 4. **Types and fields.** Every mapping recorded in step 2: the project's type or field that the team confirmed is the same part under another name. A part that is absent is not a mapping; step 2 stops for it.
48
+ 5. **Rating scale.** The integer range of the project's Business Value and Urgency fields. Confirm 1 to 5 or take the range the team names.
49
+ 6. **Sprint length.** One of 7, 14, 21 or 28 calendar days: the whole weeks one sprint covers. Propose it from the scan's `iterations`: count the weeks from one iteration's `startDate` to the next iteration's `startDate` (a Monday-to-second-Friday iteration is 14), and confirm it with the team.
50
+
51
+ Write the answers into `humanBacklog.profile` and keep every other key of the settings file as it is.
@@ -0,0 +1,31 @@
1
+ # Eject
2
+
3
+ An Eject is one zip of one Client Skill Set, for a client that runs the skills outside a Harness Intelligence repository. `python3 scripts/ado.py eject --from DIR --out PATH` builds it from the rendered folder `DIR` and makes no write to Azure DevOps. It refuses unless the `render.py check` rules pass on `DIR` and `doctor` reports `ready`. Only the generator's own `scripts/ado.py` Ejects; the `ado.py` inside a Client Skill Set refuses `eject` and says to regenerate.
4
+
5
+ The same inputs give the same zip bytes: entries are sorted and carry fixed timestamps. The file name carries no version; `MANIFEST.json` identifies the contents.
6
+
7
+ ## Zip contents
8
+
9
+ Every file of `DIR` sits at the zip root:
10
+
11
+ - One folder per rendered client skill, each with its `SKILL.md` and `references/`.
12
+ - `human-backlog-ado/`: `SKILL.md`, `scripts/ado.py` (a byte copy of the generator's helper) and `scripts/config.json`, which holds the Human Backlog Config (`provider`, `projectUrl`, `tenant`, and `ratingsPipelineUrl` when set), the `mappings` (`types` and `fields`), `ratings` and `sprint` from the Client Profile. `ado.py` reads `config.json` beside itself as its last config source, so the client's helper works without env vars or settings.
13
+ - `README.md`: short English install steps for the client's IT.
14
+ - `MANIFEST.json`:
15
+
16
+ | Field | Value |
17
+ | -------------------- | ------------------------------------------------------------------------------------------------------------ |
18
+ | `package` | `@collective-intelligence/backlog` |
19
+ | `templateTreeSha256` | sha256 over the generator's `references/templates/` tree at render time; it identifies the template version of the package |
20
+ | `skillTreeSha256` | sha256 over every file of `DIR` except `config.json` and `RENDER.json` |
21
+ | `configSha256` | sha256 of the `config.json` bytes |
22
+ | `profileSha256` | sha256 of the Client Profile that the render used, as sorted compact JSON |
23
+ | `date` | Eject date, `YYYY-MM-DD` |
24
+
25
+ ## Client use
26
+
27
+ 1. Unzip into the folder where the client's agent loads skills, for example `.agents/skills/` or `.claude/skills/`, so the skill folders sit beside each other.
28
+ 2. Install Python 3 and the Azure CLI, then run `az login --tenant <tenant>`.
29
+ 3. Run `python3 human-backlog-ado/scripts/ado.py doctor` from that folder; expect `ready`.
30
+
31
+ A client gets a template update only from a new zip: the team regenerates from the saved Client Profile and sends it. To compare two Ejects, compare `templateTreeSha256` for the template version, `skillTreeSha256` for the skills, `configSha256` for the config and `profileSha256` for the Client Profile.
@@ -2,6 +2,8 @@
2
2
 
3
3
  The team creates this process once per client organization, by hand: an inherited process in **Organization settings → Process**, assigned to the client project. Clients change only content, never the types, fields or Human States. `ado.py doctor` compares the project with this page and writes nothing.
4
4
 
5
+ A client's process may name a type or field differently. The Client Profile maps it (`types` and `fields`, see [`client-profile.md`](client-profile.md)); `doctor` then checks the mapped name, and the generated skills use the client's name. The eight Human States keep the exact names below.
6
+
5
7
  ## Work-item types
6
8
 
7
9
  | Type | Backlog level | Parent |
@@ -23,16 +25,16 @@ Every type keeps the standard System fields that the skills read or write: Title
23
25
  | Business Request | `Custom.Requester` | `Requester` | text: email, or `Display Name <email>` |
24
26
  | Business Request | `Custom.RequestDate` | `RequestDate` | date |
25
27
  | Business Request | `Microsoft.VSTS.Scheduling.TargetDate` | `TargetDate` | date, required |
26
- | Business Request | `Custom.BusinessValueScore` | `BusinessValue` | integer 1–5, required |
27
- | Business Request | `Custom.Urgency` | `Urgency` | integer 1–5, required |
28
+ | Business Request | `Custom.BusinessValueScore` | `BusinessValue` | integer on the rating scale, required |
29
+ | Business Request | `Custom.Urgency` | `Urgency` | integer on the rating scale, required |
28
30
  | Business Request | `Microsoft.VSTS.Common.Priority` | `Priority` | integer |
29
31
  | Feature | `Microsoft.VSTS.Common.AcceptanceCriteria` | `AcceptanceCriteria` | rich text |
30
- | Feature | `Custom.BusinessValueScore` | `BusinessValue` | integer 1–5, derived from linked Business Requests |
31
- | Feature | `Custom.Urgency` | `Urgency` | integer 1–5, derived from linked Business Requests |
32
+ | Feature | `Custom.BusinessValueScore` | `BusinessValue` | integer, derived from linked Business Requests |
33
+ | Feature | `Custom.Urgency` | `Urgency` | integer, derived from linked Business Requests |
32
34
  | Product Backlog Item | `Microsoft.VSTS.Common.AcceptanceCriteria` | `AcceptanceCriteria` | rich text |
33
35
  | Bug | `Microsoft.VSTS.TCM.ReproSteps` | `ReproSteps` | rich text |
34
36
 
35
- Title and Description are also required on a Business Request. The legacy `Microsoft.VSTS.Common.BusinessValue` field stays unused.
37
+ Title and Description are also required on a Business Request. The rating scale is 1 to 5 unless the Client Profile sets `ratings`. The legacy `Microsoft.VSTS.Common.BusinessValue` field stays unused.
36
38
 
37
39
  Keep every other field optional. `doctor` asks Azure DevOps to validate, without saving, one create per type with only the fields the skills always set; a rule that refuses it, such as a required Requester, Request Date or Success Criteria, is a mismatch.
38
40
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: analyze-business-request
3
- description: Analysis of an existing Business Request into Human Backlog Epics, Features and PBIs in Azure DevOps. Finds existing coverage, extends eligible Features, creates the missing items and links them to the Business Request without changing it. Use to refine, decompose or check the backlog coverage of an existing Business Request; use create-business-request for a new business ask.
3
+ description: Analysis of an existing Business Request into {{client.name}} Human Backlog Epics, Features and PBIs in Azure DevOps. Finds existing coverage, extends eligible Features, creates the missing items and links them to the Business Request without changing it. Use to refine, decompose or check the backlog coverage of an existing Business Request; use create-business-request for a new business ask.
4
4
  ---
5
5
 
6
6
  # Analyze a Business Request into a backlog
@@ -9,19 +9,25 @@ The goal is a backlog that speaks for itself: every requested capability or deli
9
9
 
10
10
  This is a long, iterative session by design. A wrong "this already exists" or a Feature cut along the wrong line is expensive to undo later, so prefer several short rounds of questions over guessing. The user knows the business; you know the backlog after you've read it — combine the two.
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
  ## The model
15
17
 
16
18
  - Hierarchy: **Epic → Feature → Product Backlog Item** (Bugs sit at PBI level).
17
19
  - A **Business Request** sits at Feature level, next to Features. It never has a parent Epic and never has children.
18
20
  - The Business Request is immutable during this analysis: do not change its fields or ratings, and do not post discussion comments on it. It takes exactly two kinds of write: the approved Related links to Features, with their coverage comments, and the move from Received to In analysis in step 8, whose `set-state` comment is the only discussion comment. Record refinements in the backlog, not in the Business Request.
19
- - Business Request ↔ Feature is a **Related** link with a comment saying what it covers, written in words, since the Business Request itself has no numbers: `Realizes Business Request #123: new hires find onboarding documents; employees find HR documents in one place` for new Features, `Already covers Business Request #123: finding a document by describing it (Done)` for existing ones. Linking existing Features too means the Business Request shows its full coverage at a glance.
20
- - No Effort, Story Points, Remaining Work, legacy Business Value, Time Criticality, Start or Target Date in the fields you create or update. The plan applier rejects these fields on new items; apply the same restriction when updating existing Features. Preserve customer-supplied timing and approval constraints in the descriptions without turning them into a delivery commitment. The new 1–5 BusinessValue and Urgency on Features are the derived exception described below; do not copy ratings to Epics, PBIs or Bugs. Leave Priority, Assigned To and Iteration alone unless the user asks.
21
+ - Business Request ↔ Feature is a **Related** link with a comment saying what it covers, written in words, since the Business Request itself has no numbers. The comment forms follow this list. Linking existing Features too means the Business Request shows its full coverage at a glance.
22
+ - No Effort, Story Points, Remaining Work, legacy Business Value, Time Criticality, Start or Target Date in the fields you create or update. The plan applier rejects these fields on new items; apply the same restriction when updating existing Features. Preserve customer-supplied timing and approval constraints in the descriptions without turning them into a delivery commitment. The {{ratings.min}}–{{ratings.max}} BusinessValue and Urgency on Features are the derived exception described below; do not copy ratings to Epics, PBIs or Bugs. Leave Priority, Assigned To and Iteration alone unless the user asks.
23
+
24
+ Related link comments, the first for a new Feature and the second for an existing one:
25
+
26
+ {{slot:coverage-comments}}
21
27
 
22
28
  ## Business Value and Urgency
23
29
 
24
- - Read the Business Request's **BusinessValue** (`Custom.BusinessValueScore`) and **Urgency** (`Custom.Urgency`). Both are integers from 1 (minimum) to 5 (maximum), entered by the business. If either is missing or invalid, report the gap and continue drafting the mapping where possible. Do not edit the Business Request, guess a score, substitute Priority, or derive Urgency from a date. Do not apply operations that require unknown source scores; resolving the source data is outside this analysis workflow.
30
+ - Read the Business Request's **BusinessValue** and **Urgency**. Both are integers from {{ratings.min}} (minimum) to {{ratings.max}} (maximum), entered by the business. If either is missing or invalid, report the gap and continue drafting the mapping where possible. Do not edit the Business Request, guess a score, substitute Priority, or derive Urgency from a date. Do not apply operations that require unknown source scores; resolving the source data is outside this analysis workflow.
25
31
  - For each new or eligible existing Feature, compute the **maximum of all Related Business Requests**, separately for the two fields. Use every linked Business Request, including Business Requests in terminal states; do not introduce a state filter or use a sum, average, or only the Business Request currently being analyzed. For example, Business Request values 3, 4 and 5 yield Feature Business Value 5; Urgency is calculated independently and may come from a different Business Request.
26
32
  - Only **New** and **Planned** Features may have their ratings recalculated. From **Committed** onward, preserve the values, even when a new Business Request is linked or an existing Business Request's ratings change. Removed Features are not eligible either. Related links may still record coverage without changing the frozen ratings or scope.
27
33
  - Preview the derived values and contributing Business Requests, or clearly label the Feature as frozen. Do not ask the user to score Features independently. A missing or invalid linked Business Request score means the maximum is unknown; report the gap instead of silently treating it as a low score.
@@ -39,7 +45,7 @@ python3 <ado> get <Business Request id>
39
45
 
40
46
  Stop if the item isn't a Business Request. If it already has Related links, an earlier session refined part of it: show what's linked and treat this as a resume.
41
47
 
42
- A Business Request written with `create-business-request` summarizes the request under **What we want**. Extract the requirements from the whole Business Request: **Business details**, **Flow and cases**, **Rules**, **Deliverables and approvals**, **Context and Existing Assets**, and any supplied **Success Criteria**. Read source and approval scope carefully. Include intermediate deliverables, mandatory customer constraints and conditions that must be met before other work starts, even if they appear only outside the summary. Compare this complete request with the backlog to establish what already exists and what must change.
48
+ A Business Request written with `create-business-request` summarizes the request under **What we want**. Its section headings are in {{language.name}}; match them by meaning. Extract the requirements from the whole Business Request: **Business details**, **Flow and cases**, **Rules**, **Deliverables and approvals**, **Context and Existing Assets**, and any supplied **Success Criteria**. Read source and approval scope carefully. Include intermediate deliverables, mandatory customer constraints and conditions that must be met before other work starts, even if they appear only outside the summary. Compare this complete request with the backlog to establish what already exists and what must change.
43
49
 
44
50
  Number capabilities and deliverables N1…Nn, and rules, constraints and approval conditions R1…Rn, in the order they appear. Use those temporary identifiers in the coverage matrix and discussion; use words in saved item descriptions and link comments. Every Feature and PBI must respect the requirements that apply to it. An older or hand-written Business Request may need its requests restated as clear capabilities or deliverables before mapping.
45
51
 
@@ -186,8 +192,8 @@ python3 <ado> search "document search" --types epic,feature,pbi
186
192
  python3 <ado> apply PLAN.json [--dry-run]
187
193
  python3 <ado> update <existing Feature id> --json FILE [--dry-run]
188
194
  python3 <ado> sync-ratings [42 43 | --all] [--dry-run] # maxima from all linked Business Requests; frozen Features skipped
189
- python3 <ado> link 123 42 --type related --comment "Already covers Business Request #123: finding a document by describing it (Done)"
190
- python3 <ado> set-state 123 "In analysis" --comment "Analysis started on 2026-10-30."
195
+ python3 <ado> link 123 42 --type related --comment "<Related link comment in the form above>"
196
+ python3 <ado> set-state 123 "In analysis" --comment "<one sentence: the analysis started and the date>"
191
197
  ```
192
198
 
193
199
  `backlog` and `search` truncate long text to 600 and 400 characters respectively; pass `--chars 0` when you need full descriptions of a few candidates, or `get` them.
@@ -50,7 +50,7 @@
50
50
  | `items[].type` | `epic`, `feature`, `pbi` or `bug`. |
51
51
  | `items[].parent` | An existing work item ID (integer) or the key of an item listed earlier. Required for Features (parent: Epic), PBIs and Bugs (parent: Feature). Epics have none. |
52
52
  | `items[].fields` | Friendly field names, as in `ado.py`: `Title`, `Description`, `AcceptanceCriteria`, `Tags`, `Priority`… Rich-text fields accept the Markdown subset. |
53
- | `links[]` | Related links only. `from`/`to` are IDs or item keys; `comment` explains the coverage. |
53
+ | `links[]` | Related links only. `from`/`to` are IDs or item keys; `comment` explains the coverage in a form from `../SKILL.md`. |
54
54
 
55
55
  Business Request fields, ratings, state and discussion history are immutable in this workflow. Only approved Business Request ↔ Feature Related links may be added, with their coverage comments. Omit `brComment` and `brCommentPosted`: the general-purpose helper supports them, but they would write to the Business Request and must not be used by this skill. Present the coverage and decision log to the user; record refinements in the affected Feature/PBI content.
56
56
 
@@ -104,8 +104,8 @@ For a customer-requested preliminary mockup, create a Feature with the agreed re
104
104
 
105
105
  ## Derived Feature ratings
106
106
 
107
- Every new Feature must have at least one Related Business Request in `links`. Each source Business Request must have BusinessValue and Urgency as integers 1–5. The applier derives these fields from all the Feature's planned Related Business Requests before creating it; do not score a Feature independently. If these fields are included explicitly, they must equal the computed maxima. They are not allowed on Epics, PBIs or Bugs.
107
+ Every new Feature must have at least one Related Business Request in `links`. Each source Business Request must have BusinessValue and Urgency as integers {{ratings.min}}–{{ratings.max}}. The applier derives these fields from all the Feature's planned Related Business Requests before creating it; do not score a Feature independently. If these fields are included explicitly, they must equal the computed maxima. They are not allowed on Epics, PBIs or Bugs.
108
108
 
109
109
  After applying links, the helper recalculates both dimensions separately on eligible Features in New or Planned. From Committed onward, ratings are frozen, and adding a Related Business Request does not change them. The report's `feature_ratings` records updated, unchanged, frozen, or needs_input results. Report missing source scores without changing the Business Request. Drafting may continue, but do not apply operations whose required ratings cannot be derived from recorded source values.
110
110
 
111
- The legacy `Microsoft.VSTS.Common.BusinessValue` remains forbidden. JSON `BusinessValue` now refers to `Custom.BusinessValueScore`; `Urgency` refers to `Custom.Urgency`.
111
+ The legacy `Microsoft.VSTS.Common.BusinessValue` remains forbidden. JSON `BusinessValue` and `Urgency` name the rating fields; the helper maps them to this project's fields.
@@ -1,13 +1,15 @@
1
1
  ---
2
2
  name: create-bug
3
- description: Bug intake for the Human Backlog in Azure DevOps, guided for a business user. Works from screenshots, a screen recording, recorded speech or written input; clarifies observed and expected behavior, checks duplicates, finds the parent Feature, and creates the approved Bug, with no parent when no reliable Feature exists. Use when a business user reports a platform problem; technical investigation stays out.
3
+ description: Bug intake for the {{client.name}} Human Backlog in Azure DevOps, guided for a business user. Works from screenshots, a screen recording, recorded speech or written input; clarifies observed and expected behavior, checks duplicates, finds the parent Feature, and creates the approved Bug, with no parent when no reliable Feature exists. Use when a business user reports a platform problem; technical investigation stays out.
4
4
  ---
5
5
 
6
6
  # Create a Bug
7
7
 
8
8
  Help a business user turn an observed platform problem into a clear Bug. The user is not expected to know the backlog or the parent Feature. Research that association yourself and explain the proposed match in everyday language.
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. Preserve exact error messages and relevant UI labels in their original language. Technical diagnosis, solution design and implementation work are out of scope and managed 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. Preserve exact error messages and relevant UI labels in their original language. Technical diagnosis, solution design and implementation work are out of scope and managed 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
  ## Working rules
13
15
 
@@ -24,7 +26,7 @@ Read the supplied text and inspect the screenshots, video and audio using the ca
24
26
 
25
27
  If a relevant screen recording has not already been supplied, proactively suggest one early in the conversation, for example:
26
28
 
27
- > Can you record a short screen video while you reproduce the problem and attach it here in the chat? Show where you start, what you do and what happens; if you like, also say what you expected. It helps me rebuild the steps and prepare the Bug.
29
+ {{slot:recording-request}}
28
30
 
29
31
  Make this an optional aid, not a prerequisite. Continue researching and preparing the report while the user records. If they cannot provide a video or prefer to proceed with sufficient text/screenshots, continue without insisting. When the user says a recording is coming, incorporate it before finalizing the report. Ask for attachments in normal chat rather than a text-only question tool.
30
32
 
@@ -126,9 +128,9 @@ Re-read the Bug to verify its fields, parent or absence of parent, and attached
126
128
 
127
129
  Return the Bug ID and URL, the parent Feature or **no parent**, and any incomplete evidence transfer. Do not require the user to understand work-item types to use the result.
128
130
 
129
- For every created Bug without a parent, explicitly ask the user to communicate its ID to the developer and provide a ready-to-copy message in their language:
131
+ For every created Bug without a parent, explicitly ask the user to communicate its ID to the developer and provide a ready-to-copy message:
130
132
 
131
- > I opened Bug #123: ‹URL›. It has no parent Feature because no reliable match was found. Can you check it and link it to the correct Feature?
133
+ {{slot:no-parent-message}}
132
134
 
133
135
  Use the actual returned ID and URL, and adapt the reason if research was unavailable. The user forwards this message; do not contact the developer automatically. A no-parent Bug is a created report awaiting association, not a failed intake.
134
136
 
@@ -13,7 +13,7 @@ This example assumes the user confirmed the date change, reload and impact. Actu
13
13
  }
14
14
  ```
15
15
 
16
- `ReproSteps` maps to `Microsoft.VSTS.TCM.ReproSteps`; the helper converts the supported Markdown to HTML. Do not put parent IDs into this field or the field JSON. Supply the selected Feature through `--parent`:
16
+ The helper converts the supported Markdown in `ReproSteps` to HTML. Do not put parent IDs into this field or the field JSON. Supply the selected Feature through `--parent`:
17
17
 
18
18
  ```bash
19
19
  python3 <ado> create --type bug --json /tmp/bug.json --parent 55 --dry-run