@collective-intelligence/backlog 0.0.0-stage → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,139 @@
1
+ ---
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.
4
+ ---
5
+
6
+ # Plan a Sprint
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.
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.
11
+
12
+ ## 1. Establish the sprint and available developers
13
+
14
+ Before producing an allocation, ask how many developers will be available in the target sprint. Reuse information already supplied. Clarify only the relevant exceptions: full or partial availability, absences, other project commitments, ongoing work and known Bug work. Do not infer availability from the number of team members.
15
+
16
+ Assume comparable developer pace with supervised AI assistance, as agreed by the team. Do not invent per-person productivity rankings or an AI speed multiplier.
17
+
18
+ Read the configured team, sprint dates, working days and member identities. `<ado>` is `../human-backlog-ado/scripts/ado.py` relative to this skill's directory. When it stops on the Human Backlog Config or on Azure CLI sign-in, follow `../human-backlog-ado/SKILL.md`.
19
+
20
+ ```bash
21
+ python3 <ado> planning-context
22
+ python3 <ado> planning-context --team "<team>"
23
+ python3 <ado> planning-context --team "<team>" --iteration "<sprint ID or path>"
24
+ ```
25
+
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.
27
+
28
+ 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
+
30
+ **Done when:** the target team and sprint have actual dates and paths, and each participating developer has a confirmed net availability.
31
+
32
+ ## 2. Read candidates and existing load
33
+
34
+ ```bash
35
+ python3 <ado> backlog --types feature,bug --chars 0
36
+ python3 <ado> get <candidate Feature IDs>
37
+ python3 <ado> backlog --under <Feature ID> --types pbi,bug --include-removed --chars 0
38
+ ```
39
+
40
+ Start with eligible **New/Planned Features ordered by Urgency**, highest first. At equal urgency, consider Business Value, requested dates and dependencies, explaining the order. Missing scores are unknown, not zero; do not edit Business Request scores during planning.
41
+
42
+ Read full descriptions, scope, acceptance criteria, relevant PBIs and referenced context. Inspect customer approval conditions and mandatory constraints. Titles, PBI counts and labels alone do not establish size or feasibility.
43
+
44
+ Read work already assigned to the sprint, and any ongoing work that consumes the selected developers' availability even if recorded in another sprint. The context query includes project-level Feature/Bug work for the iteration; distinguish the participating developers from other team members. Existing Committed or started Features remain fixed load. Do not silently move or reassign them to make the proposal fit.
45
+
46
+ Treat already-planned work explicitly: retain it in the package, reserve its remaining load, or propose its removal/move for agreement. Do not fill the sprint as though it were empty. Count a shared Feature once, regardless of how many Business Requests it serves.
47
+
48
+ **Done when:** every New or Planned candidate is listed in Urgency order with its full scope read, and you know the existing sprint load.
49
+
50
+ ## 3. Pre-assess Features before asking the operator to select
51
+
52
+ Perform the first assessment yourself from the evidence. For each candidate, propose:
53
+
54
+ - **Potential size:** short, medium or long, or not assessable yet.
55
+ - **Indicative duration:** a range in working days for one developer at the team's agreed AI-assisted pace.
56
+ - **Confidence:** high, medium or low, with concrete reasons and relevant unknowns.
57
+ - **Sprint fit:** a plausible candidate, a tight/risky candidate, or potentially requiring subdivision.
58
+
59
+ Explain the assessment using functional breadth, distinct flows, roles, business rules, relevant exceptions, documented reuse, dependencies and the amount of new behavior. A visual prototype is not evidence that persistence, authorization or integrations already work. Keep uncertainty separate from size; incomplete information does not automatically mean a long Feature.
60
+
61
+ Use relevant completed work or an operator-confirmed reference when available. Otherwise state that the initial duration ranges are planning hypotheses, explain their basis and let the operator correct them. Do not fabricate historical throughput or wait for the operator to estimate every Feature before offering a first analysis. Read `references/assessment-guide.md` for examples and calibration guidance.
62
+
63
+ Planning hypotheses stay in the discussion/local proposal. Do not write Effort, Story Points, Remaining Work, artificial size tags or estimated dates into backlog items. The existing Business Value and Urgency scores are prioritization inputs, not work estimates.
64
+
65
+ **Done when:** every candidate has a size, a duration range, a confidence and a sprint fit, each with its reasons.
66
+
67
+ ## 4. Build a sequence per developer
68
+
69
+ Build a concrete proposed package starting with the urgent work. A developer can take several short Features sequentially; increasing the number of developers increases parallel Feature capacity, not the speed of one Feature through an assumed division of its duration.
70
+
71
+ Choose a defensible planning duration within each discussed range and show it. Use the upper end when uncertainty warrants it, and disclose a tighter assumption. Account for existing work and any reserve explicitly agreed with the operator. Do not invent a fixed reserve percentage or a fixed number of Features per sprint.
72
+
73
+ Check two separate conditions:
74
+
75
+ 1. Each developer's selected and reserved work fits their net availability.
76
+ 2. The sequence, actual absence dates, dependencies and approvals permit every Feature to finish within the sprint.
77
+
78
+ A total team budget alone is insufficient. Unused days on one developer do not cure another developer's overload. Cross-developer dependencies can also delay work even when both numerical budgets fit.
79
+
80
+ Show which urgent Features are excluded and why. Do not silently replace a difficult urgent Feature with many easier low-priority ones. If a Feature appears too large, propose a functional subdivision for agreement before scheduling; do not split its PBIs across sprints while keeping the same Feature, or silently change scope to fit.
81
+
82
+ Let the operator correct the size/duration assessments, select the package, adjust ownership and choose trade-offs. They represent the team's capacity judgment. Present per developer the ordered Features, expected outcomes, duration hypotheses, remaining capacity and relevant risks. PBI execution order remains outside this planning session.
83
+
84
+ For several future sprints, repeat the process with availability for each period. Track Feature assignments across the proposals so an item is not promised twice or silently moved by a later plan. Future scheduling remains a forecast until explicitly committed.
85
+
86
+ **Done when:** each developer has an ordered sequence that fits their net availability, and every excluded urgent Feature has a reason.
87
+
88
+ ## Bugs
89
+
90
+ When Bugs are included in planning, account for their work within the developer's availability and sequence. Do not assume Bug work is free parallel capacity. A Bug may have its own sprint even if its parent Feature was delivered earlier, or if no parent has yet been found.
91
+
92
+ Plan the Bug itself; do not move the parent Feature or siblings as a consequence. A Bug already in progress is fixed load rather than a normal scheduling candidate. Preserve its workflow state. Avoid double-counting a Bug both as a separately reserved item and inside a Feature duration.
93
+
94
+ ## 5. Preview the complete assignment
95
+
96
+ Read `references/operations.md` for the temporary proposal format, read-only checks and supported writes. The final preview must show:
97
+
98
+ - the target sprint and actual dates;
99
+ - the chosen developers, availability and existing/reserved load;
100
+ - each selected Feature/Bug and its developer;
101
+ - existing-to-proposed sprint/owner changes, including moves out of another planned sprint;
102
+ - Feature-to-PBI sprint propagation;
103
+ - the duration assumptions, dependencies, approval conditions and exclusions.
104
+
105
+ Obtain approval of this concrete allocation, reusing an explicit approval already given for the same plan. Operator feedback may change the assessment and selection; rerun the checks after a material change. A numerical check passing is not confirmation of technical feasibility or of an external approver's availability.
106
+
107
+ **Done when:** `planning-check` passes and the operator approves the concrete allocation.
108
+
109
+ ## 6. Apply scheduling, then optionally commit
110
+
111
+ Before writes, refresh the target calendar, current load and selected item/child snapshots. Reconcile unexpected state, scope, ownership or hierarchy changes with the operator.
112
+
113
+ Normal scheduling changes only:
114
+
115
+ - **Feature:** IterationPath, AssignedTo and State = Planned.
116
+ - **Its relevant PBIs:** IterationPath only. Preserve their AssignedTo, state, order and content; exclude Removed PBIs. Do not move completed or started PBIs out of their historical sprint to disguise carryover.
117
+ - **Selected Bug:** IterationPath and AssignedTo, preserving state and parent.
118
+
119
+ Epics and Business Requests are not assigned to the sprint; a Business Request changes only its Human State, in step 7. Do not change scope, technical details, priority scores or estimates during application. Keep Committed/started Features out of normal scheduling updates. If an inconsistency requires a scope revision or a changed commitment, address that separately rather than silently overriding it.
120
+
121
+ Use the reviewed revisions for updates, retain operation results and verify all Feature/PBI assignments after application. These updates span multiple items and are not atomic; stop dependent writes on failure and report the partial result before retrying.
122
+
123
+ **Planned is not Committed.** Only after an explicit instruction to commit the specified package may the skill transition those Features to Committed, using the helper's rating reconciliation and validation. Calendar assignment alone does not authorize this transition. Do not change PBI execution states as part of committing the Feature.
124
+
125
+ Return the sprint, Feature/Bug assignments per developer, propagated PBI count and any partial result or unresolved dependency. Keep the difference between a forecast and an explicitly committed package clear.
126
+
127
+ **Done when:** every Feature and PBI assignment is verified, or the partial result is reported, and the user has the assignments per developer and the propagated PBI count.
128
+
129
+ ## 7. Move Business Requests to Planned
130
+
131
+ A request whose first linked Feature gets a sprint moves to Planned. For each Feature that step 6 assigned to the sprint, read its Related Business Requests with `python3 <ado> get <Feature id>`, then `python3 <ado> get <Business Request ids>`. For each Business Request in Received or In analysis, run:
132
+
133
+ ```bash
134
+ python3 <ado> set-state <Business Request id> Planned --comment "<one sentence in the Business Request's language: the sprint name and its dates>"
135
+ ```
136
+
137
+ Leave a Business Request in any other Human State as it is. When `set-state` refuses, report its error to the user and continue with the next request.
138
+
139
+ **Done when:** every Business Request that was Received or In analysis and is linked to a Feature assigned in step 6 reads back Planned, or the user has the refusal for it.
@@ -0,0 +1,49 @@
1
+ # Feature assessment and calibration
2
+
3
+ Assess whole Features for one developer working with supervised AI. The expected pace is comparable across the available developers. Do not infer staffing needs or technical solutions from the title.
4
+
5
+ ## Evidence to inspect
6
+
7
+ - Requested user operations and how many distinct workflows must work together.
8
+ - Roles, permissions, business rules and meaningful exception paths.
9
+ - Acceptance criteria and the functional scope represented by the PBIs.
10
+ - Existing capabilities explicitly documented as working, and what must actually change.
11
+ - Required approvals, other Features, external services or supplied materials on which delivery depends.
12
+ - Any previous similar work whose scope, staffing and duration are sufficiently known to be a useful comparison.
13
+
14
+ Several PBIs may describe one small behavior, while one PBI may contain a substantial workflow. Use their content, not the count. A prototype with a filename placeholder does not establish that real file storage and access rules already work.
15
+
16
+ ## Qualitative categories
17
+
18
+ - **Short:** a narrow result with a small number of behaviors and limited dependencies.
19
+ - **Medium:** several coordinated behaviors or rules within a clear boundary.
20
+ - **Long:** multiple flows, roles or dependencies, or a substantial amount of new behavior.
21
+ - **Not assessable yet:** material information is missing and even a broad duration hypothesis would be misleading. Name the missing information and ask a focused question.
22
+
23
+ These are relative categories, not fixed point values or a universal conversion to days. Use the same working calibration for the team's candidates and explain deviations. Confidence reflects the strength of the evidence, not the desirability or urgency of the Feature.
24
+
25
+ ## Duration hypotheses
26
+
27
+ Propose a range rather than an unsupported exact promise. State whether it comes from a useful past comparison, a team reference supplied by the operator, or an initial heuristic reading of the functional scope. If no history exists, a first hypothesis is still useful when its assumptions and low confidence are explicit. Do not present invented AI-assisted throughput as measured productivity.
28
+
29
+ The operator can correct a range using knowledge not present in the tickets. Record the correction and its reason in the proposal. Planning uses an explicitly chosen value from the discussed range; the range and chosen duration are not written into Effort, Story Points or tags.
30
+
31
+ Example assessment wording:
32
+
33
+ > Potentially medium, moderate confidence. The scope includes creation, editing and viewing requests, with defined roles. The referenced integration's availability remains unverified. The duration range is a planning hypothesis that assumes the integration is already usable; confirm or revise that assumption before committing.
34
+
35
+ Do not infer database changes, libraries, code components or an implementation backlog. Identify an uncertainty such as “integration readiness is unknown” and leave technical investigation separate.
36
+
37
+ ## Capacity and sequence
38
+
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
+
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.
42
+
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
+
45
+ ## Preserve urgency in the proposal
46
+
47
+ Begin from the most urgent Features and explain size/fit constraints. Keep an urgent long or uncertain Feature visible, with the decision needed: clarify, accept a defensible tighter estimate, subdivide the functional scope, or defer it explicitly. Do not bury it beneath low-urgency short work without explanation.
48
+
49
+ The output is a proposed sprint package with reasons and uncertainty, followed by the operator's selection. A successful capacity check does not turn uncertain duration hypotheses into a delivery guarantee.
@@ -0,0 +1,111 @@
1
+ # Planning context and application
2
+
3
+ Use the shared helper `<ado>` named in `../SKILL.md`. Planning-context and planning-check are read-only. Assignment uses the existing revision-checked update command after the operator approves the concrete plan.
4
+
5
+ ## Discover the calendar and identities
6
+
7
+ ```bash
8
+ python3 <ado> planning-context
9
+ python3 <ado> planning-context --team "<actual team name or ID>"
10
+ python3 <ado> planning-context --team "<team>" --iteration "<actual iteration ID or path>"
11
+ ```
12
+
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
+
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.
16
+
17
+ ## Temporary proposal
18
+
19
+ Save a local JSON proposal. This example uses illustrative IDs and identities that must be replaced with actual context values; the durations are hypothetical, not a default calibration:
20
+
21
+ ```json
22
+ {
23
+ "team": "team-id-from-context",
24
+ "iteration": "iteration-id-from-context",
25
+ "developers": [
26
+ {
27
+ "identity": "dev.one@example.com",
28
+ "availableDays": 10,
29
+ "reservedDays": 1
30
+ },
31
+ { "identity": "dev.two@example.com", "availableDays": 8, "reservedDays": 0 }
32
+ ],
33
+ "existingLoad": [{ "id": 70, "developer": "dev.one@example.com", "days": 2 }],
34
+ "items": [
35
+ {
36
+ "id": 55,
37
+ "developer": "dev.one@example.com",
38
+ "days": 4,
39
+ "size": "medium",
40
+ "confidence": "moderate",
41
+ "reason": "Operator-reviewed functional assessment"
42
+ },
43
+ {
44
+ "id": 56,
45
+ "developer": "dev.one@example.com",
46
+ "days": 2,
47
+ "size": "short",
48
+ "confidence": "moderate",
49
+ "reason": "Operator-reviewed functional assessment"
50
+ },
51
+ {
52
+ "id": 60,
53
+ "developer": "dev.two@example.com",
54
+ "days": 6,
55
+ "size": "long",
56
+ "confidence": "moderate",
57
+ "reason": "Operator-reviewed functional assessment"
58
+ }
59
+ ]
60
+ }
61
+ ```
62
+
63
+ - `developers` lists actual available people, using their confirmed team-member email/uniqueName. Provisional developer slots must be resolved before this check.
64
+ - `availableDays` is net availability within the remaining sprint after absences. `reservedDays` is an explicitly agreed reserve for other commitments not already counted in existingLoad; do not deduct it twice.
65
+ - `existingLoad` records remaining work on existing unfinished Features/Bugs, including carryover known to consume capacity. It does not change their sprint, owner or state. An existing owner's identity must match the reservation.
66
+ - `items` contains whole Features and individual Bugs to schedule. Each ID appears once and has one developer. Its `days` value is the chosen temporary duration hypothesis. Array order defines the proposed sequence for each developer.
67
+ - Keep size, duration ranges, rationale, confidence, dated absences and dependencies in the local proposal/review. The helper uses selected days for budget checking but does not persist these estimates in Azure.
68
+
69
+ Do not put PBIs, Business Requests or Epics in `items`. PBIs are collected from each selected Feature and receive only its iteration. Bugs are independent scheduling items and do not propagate their sprint to a parent Feature.
70
+
71
+ ## Check the proposal
72
+
73
+ ```bash
74
+ python3 <ado> planning-check /tmp/sprint-plan.json
75
+ ```
76
+
77
+ The check reads the latest team calendar and items. It verifies:
78
+
79
+ - confirmed, distinct developer identities and finite availability/duration numbers;
80
+ - a budget for each developer, including existing work and reserve;
81
+ - one allocation per Feature/Bug;
82
+ - eligible Feature/Bug states and complete accessible child information;
83
+ - PBI iteration consistency without moving started/completed work into another sprint;
84
+ - existing target-sprint load for participating developers, including unassigned work that needs a decision.
85
+
86
+ It returns `updates` containing only allowed field changes and `expectedRev`, plus capacity and item snapshots. A blocked result returns no executable updates and exits nonzero. Ineligible items are not silently omitted to make the rest of the plan pass.
87
+
88
+ The helper does not validate technical feasibility, actual leave dates, external approvals or a complete dependency schedule. Review those separately. It also cannot infer carryover from another sprint merely from the target-sprint query; inspect ongoing work and include its remaining load where relevant. Do not hide unaccounted work by adding a reserve without identifying its effect on the selected developers.
89
+
90
+ ## Apply the reviewed fields
91
+
92
+ After approval, refresh the context and rerun planning-check. Compare the result, selected item content and child set with the approved proposal. If scope, state, owner, calendar or existing load changed unexpectedly, reconcile before applying.
93
+
94
+ For each reviewed update, save only its `fields` object to a field JSON file, then use its actual `expectedRev`:
95
+
96
+ ```bash
97
+ python3 <ado> update 55 --json /tmp/feature-55-planning.json --expected-rev 7 --dry-run
98
+ python3 <ado> update 55 --json /tmp/feature-55-planning.json --expected-rev 7
99
+ ```
100
+
101
+ Feature fields can contain IterationPath, AssignedTo and State = Planned. PBI fields contain IterationPath only. Bug fields can contain IterationPath and AssignedTo, with state and parent preserved. Do not copy local planning metadata into field files or introduce estimates, StartDate or TargetDate.
102
+
103
+ The update dry run previews operations locally; it is not Azure-side validation of all fields. The real update is revision-checked. Keep the generated field files and operation results, and re-read affected items after applying. If hierarchy changes or an update fails, stop dependent writes and report what succeeded. Updates across a Feature and its PBIs are not atomic; do not claim complete alignment before verifying it.
104
+
105
+ On retry, compare actual saved fields with the intended results. Reuse successful work rather than blindly applying stale revisions. Do not reset developer PBI assignments, reorder PBIs or change execution states.
106
+
107
+ ## Explicit commitment
108
+
109
+ An approved calendar allocation normally leaves Features Planned. If the operator explicitly asks to commit named Features, confirm the already-reviewed sprint package and apply State = Committed in a separate field update using the current reviewed revisions. The helper reconciles Feature ratings before commitment and rejects incomplete rating sources. Do not alter Business Request ratings to bypass that check.
110
+
111
+ Do not move Committed/started Features in the normal planning flow. Keep them as fixed load; changed commitments need a separate explicit decision. PBI state transitions remain with execution, not sprint planning.
@@ -0,0 +1,83 @@
1
+ ---
2
+ name: setup-human-backlog
3
+ description: Set up a Human Backlog in Azure DevOps. Interviews for the Human Backlog Config, writes it, proves it with the read-only `ado.py doctor` and reports `ready` or `blocked`; on request, builds an Eject zip for a client. Use when a repo or client starts using a Human Backlog, when a Human Backlog skill stops on its config, or when a client asks for the skills as a zip.
4
+ ---
5
+
6
+ # Set up a Human Backlog
7
+
8
+ Connect the Human Backlog skills to one client's Azure DevOps project, then prove the connection. Run the helper as `python3 ../human-backlog-ado/scripts/ado.py <command>` from this directory and call it `<ado>`; `../human-backlog-ado/SKILL.md` is its reference.
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.
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` only reads and compares.
13
+
14
+ ## 1. Interview for the Human Backlog Config
15
+
16
+ Ask for the values you do not have yet:
17
+
18
+ - `projectUrl`: `https://dev.azure.com/{org}/{project}`.
19
+ - `tenant`: the Entra tenant ID (a GUID) that the client's users sign in to.
20
+ - `ratingsPipelineUrl`: optional URL of the pipeline that reconciles Feature ratings.
21
+
22
+ `provider` is always `azure-devops`.
23
+
24
+ **Done when:** you have `projectUrl` in that form, `tenant` as a GUID, and either a `ratingsPipelineUrl` or the user's answer that there is none.
25
+
26
+ ## 2. Write the config
27
+
28
+ In a Harness Intelligence repo, set the `humanBacklog` key in the nearest `.devpunks/settings.json` above the working directory. Keep every other key and value in that file as it is.
29
+
30
+ ```json
31
+ {
32
+ "humanBacklog": {
33
+ "provider": "azure-devops",
34
+ "projectUrl": "https://dev.azure.com/<org>/<project>",
35
+ "tenant": "<tenant GUID>",
36
+ "ratingsPipelineUrl": "<URL, or leave this key out>"
37
+ }
38
+ }
39
+ ```
40
+
41
+ Without a `.devpunks/settings.json`, tell the user to keep the same keys in `../human-backlog-ado/scripts/config.json` or in the `ADO_*` env vars that `../human-backlog-ado/SKILL.md` lists. An `ADO_*` env var wins over both files; when one is set, tell the user its value replaces the one you wrote.
42
+
43
+ **Done when:** `humanBacklog` holds the interviewed values and every other settings key is unchanged, or the user knows where to keep the config.
44
+
45
+ ## 3. Run doctor
46
+
47
+ ```bash
48
+ python3 <ado> doctor
49
+ ```
50
+
51
+ `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). It writes nothing. A failing `config`, `az` or `project` check marks the checks after it `skipped`. The JSON `status` is `ready` (exit 0) only when every check passes; otherwise it is `blocked` (exit 1) with every mismatch in `mismatches`.
52
+
53
+ **Done when:** you have the `doctor` JSON.
54
+
55
+ ## 4. Report ready or blocked
56
+
57
+ On `ready`, tell the user that the Human Backlog skills can use this project.
58
+
59
+ On `blocked`, show every line of `mismatches` and the fix for its check:
60
+
61
+ | Check | Fix |
62
+ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
63
+ | `config` | Correct the key that the mismatch names, then repeat step 2. |
64
+ | `az` | Install the Azure CLI when it is missing, then run `az login --tenant <tenant>`. |
65
+ | `project` | Check `projectUrl` and that the signed-in user can open the project. |
66
+ | `types`, `fields`, `states` | The team adds the missing part to the process by hand, as `references/process.md` describes. When this file is absent (an Eject), ask the team that owns the process. |
67
+ | `iterations` | The team adds sprint iterations to the project's default team. |
68
+
69
+ After a fix, run step 3 again.
70
+
71
+ **Done when:** you reported `ready`, or `blocked` with every mismatch from the JSON and its fix.
72
+
73
+ ## 5. Eject, on request
74
+
75
+ Eject only when the user asks for a client zip and step 3 reported `ready`. Ask for the output path, then run:
76
+
77
+ ```bash
78
+ python3 <ado> eject --out <path>
79
+ ```
80
+
81
+ `<path>` is a zip file, or an existing directory that receives `human-backlog-skills.zip`. Report the `zip` path, `skillTreeSha256` and `configSha256` from the JSON. Read `references/eject.md` when the user asks what the zip holds or how a client uses it.
82
+
83
+ **Done when:** you reported the zip path and both hashes, or the user declined the Eject.
@@ -0,0 +1,26 @@
1
+ # Eject
2
+
3
+ An Eject is one zip of the installed Human Backlog skills plus a proven Human Backlog Config, for a client that runs the skills outside a Harness Intelligence repo. `python3 <ado> eject --out <path>` builds it from the skills installed beside `human-backlog-ado` and makes no network call. The file name carries no version; `MANIFEST.json` identifies the contents.
4
+
5
+ ## Zip contents
6
+
7
+ Entries sit in path order at the zip root:
8
+
9
+ - The seven Human Backlog skill folders: `analyze-business-request`, `create-bug`, `create-business-request`, `human-backlog-ado`, `plan-sprint`, `setup-human-backlog`, `update-business-request`. Other installed skills stay out, and so do `tests` folders, `__pycache__`, `.DS_Store` and `setup-human-backlog/references/process.md` (the team keeps the process).
10
+ - `human-backlog-ado/scripts/config.json`: the resolved Human Backlog Config (`provider`, `projectUrl`, `tenant`, and `ratingsPipelineUrl` when set). `ado.py` reads `config.json` beside itself as its last config source, so the ejected helper works without env vars or settings.
11
+ - `MANIFEST.json`:
12
+
13
+ | Field | Value |
14
+ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
15
+ | `package` | `@collective-intelligence/backlog` |
16
+ | `skillTreeSha256` | sha256 over every skill file in path order: its zip path in UTF-8, one NUL byte, then the sha256 of its bytes. `config.json` is not part of it. The same installed skills give the same value, so it identifies the published version. |
17
+ | `configSha256` | sha256 of the `config.json` bytes |
18
+ | `date` | Eject date, `YYYY-MM-DD` |
19
+
20
+ ## Client use
21
+
22
+ 1. Unzip into the folder where the client's agent loads skills, for example `.agents/skills/` or `.claude/skills/`, so the seven folders sit beside each other.
23
+ 2. Install Python 3 and the Azure CLI, then run `az login --tenant <tenant>`.
24
+ 3. Run `python3 human-backlog-ado/scripts/ado.py doctor` from that folder; expect `ready`.
25
+
26
+ To compare two Ejects, compare `skillTreeSha256` for the skills and `configSha256` for the config.
@@ -0,0 +1,54 @@
1
+ # Human Backlog process
2
+
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
+
5
+ ## Work-item types
6
+
7
+ | Type | Backlog level | Parent |
8
+ | -------------------- | ------------- | ------------------------------------- |
9
+ | Epic | Epics | none |
10
+ | Feature | Features | Epic |
11
+ | Business Request | Features | none; it Related-links Features |
12
+ | Product Backlog Item | Requirements | Feature |
13
+ | Bug | Requirements | Feature, or none when no Feature fits |
14
+
15
+ ## Fields
16
+
17
+ Every type keeps the standard System fields that the skills read or write: Title, Description, State, Assigned To, Iteration Path, Tags and History (comments). `doctor` checks the fields below by reference name on each type.
18
+
19
+ | Type | Reference name | Name in the skills | Value |
20
+ | -------------------- | ------------------------------------------ | -------------------- | -------------------------------------------------- |
21
+ | Business Request | `Microsoft.VSTS.Common.AcceptanceCriteria` | `SuccessCriteria` | rich text |
22
+ | Business Request | `Custom.ContextAndExistingAssets` | `Context` | rich text, required |
23
+ | Business Request | `Custom.Requester` | `Requester` | text: email, or `Display Name <email>` |
24
+ | Business Request | `Custom.RequestDate` | `RequestDate` | date |
25
+ | 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 | `Microsoft.VSTS.Common.Priority` | `Priority` | integer |
29
+ | 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
+ | Product Backlog Item | `Microsoft.VSTS.Common.AcceptanceCriteria` | `AcceptanceCriteria` | rich text |
33
+ | Bug | `Microsoft.VSTS.TCM.ReproSteps` | `ReproSteps` | rich text |
34
+
35
+ Title and Description are also required on a Business Request. The legacy `Microsoft.VSTS.Common.BusinessValue` field stays unused.
36
+
37
+ 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
+
39
+ ## Human States
40
+
41
+ A Business Request has exactly these eight states, in this order. Received is the initial state.
42
+
43
+ 1. Received
44
+ 2. In analysis
45
+ 3. Planned
46
+ 4. In progress
47
+ 5. On staging
48
+ 6. Live (final)
49
+ 7. Rejected (final)
50
+ 8. Withdrawn (final)
51
+
52
+ ## Other states the skills use
53
+
54
+ `plan-sprint` moves a Feature from New to Planned, and to Committed on an explicit request. A Feature therefore needs the states New, Planned and Committed. `doctor` does not check them.
@@ -0,0 +1,125 @@
1
+ ---
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.
4
+ ---
5
+
6
+ # Update a Business Request
7
+
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
+
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.
11
+
12
+ ## Two supported paths
13
+
14
+ 1. **Received Business Request with no linked implementation backlog:** freely edit the Business Request as requested. It stays Received; do not generate Features or PBIs as a consequence of editing. Attachments, source references and cross-references to other Business Requests are not implementation backlog.
15
+ 2. **In analysis or Planned Business Request whose linked Features are all New or Planned:** revise the Business Request and propagate additions, changes and removals to the appropriate Features and PBIs. Create missing Features, PBIs and, only where needed, Epics. The Business Request keeps its Human State.
16
+
17
+ Every other lifecycle case is blocked before any write. This includes a Received Business Request already linked to backlog, a Business Request in another Human State, and an In analysis or Planned Business Request with even one linked Feature outside New/Planned. Check the entire linked set, including work the user did not ask to change. Do not update only the Business Request, detach a protected Feature, change a state or apply the apparently safe part first to bypass this rule. Explain the blocking item and suggest a new Business Request without creating it automatically.
18
+
19
+ The same New/Planned restriction applies to existing Features newly selected for the revision. A matching Done Feature is not a reason to bypass this version's boundary. If the full relevant graph cannot be read, eligibility is unverified: do not write.
20
+
21
+ ## Rejected or Withdrawn on request
22
+
23
+ Rejected and Withdrawn are business decisions. Write one only when the user asks for that state for this Business Request; a revision, a removed Feature or a blocked path is not such a request. This path needs no `revision-check` and changes no Feature. Preview the state and the comment, then run:
24
+
25
+ ```bash
26
+ python3 <ado> set-state <Business Request ID> Rejected --comment "<the user's reason, in the Business Request's language>"
27
+ python3 <ado> set-state <Business Request ID> Withdrawn --comment "<the user's reason, in the Business Request's language>"
28
+ ```
29
+
30
+ Run only the line for the state the user named. `set-state` refuses when the request is already Live, Rejected or Withdrawn; report that error to the user.
31
+
32
+ **Done when:** `get <Business Request ID>` reads back the state the user asked for, or the user has the refusal.
33
+
34
+ ## Editing standard
35
+
36
+ - Apply the requested change without repeating the full `create-business-request` intake or its quality gates. Do not make unrelated missing detail a reason to restart the interview.
37
+ - Clarify only ambiguities or contradictions introduced by the proposed change. Preserve unaffected content, rules, constraints, deliverables, source references and approvals.
38
+ - Reuse clear authorization already given for the edit and its known consequences. Do not add a separate permission step for every ordinary unshared change. When the cascade requires choices the user has not settled, present the concrete proposal and resolve them before writing.
39
+ - A shared Feature may be read or left unchanged without extra approval. Changing its content, its PBIs, its Business Request associations, or its derived ratings requires the specific shared-impact feedback described below.
40
+ - Preserve other Business Requests' fields and states. Do not edit historical requests to make a changed shared Feature appear consistent with them.
41
+ - Remove obsolete work from scope by explicit relationship changes and, when it is being cancelled, the reversible **Removed** state. Do not hard-delete work items or automatically cancel their Epic or existing Bugs.
42
+
43
+ ## 1. Establish eligibility before planning writes
44
+
45
+ Load the current Business Request, its work-item relationships and all connected Features, with full content where needed. Do not rely on an old chat summary or the Business Request state alone.
46
+
47
+ `<ado>` is `../human-backlog-ado/scripts/ado.py` relative to this skill's directory. When it stops on the Human Backlog Config or on Azure CLI sign-in, follow `../human-backlog-ado/SKILL.md`.
48
+
49
+ ```bash
50
+ python3 <ado> get <Business Request ID>
51
+ python3 <ado> revision-check <Business Request ID>
52
+ ```
53
+
54
+ `revision-check` is read-only. It reports the allowed path, blocking states, shared Features and item revisions; a blocked result exits nonzero. Stop without writes when no path is allowed. A shared Feature reported as unaffected is informational, not a blocker by itself.
55
+
56
+ Read `references/operations.md` before preparing a cascade. It explains the required impact check, revision checks, supported commands and partial-failure handling. Use `references/examples.md` for the distinctions between ordinary edits, shared changes and blocked cases.
57
+
58
+ **Done when:** `revision-check` reports an allowed path, or you have stopped without writes and named the blocking item to the user.
59
+
60
+ ## 2. Identify the requested delta
61
+
62
+ Compare the existing Business Request with the requested revision. Identify what is added, changed, removed and preserved. Reuse the user's explanation; ask only for missing decisions that affect this change.
63
+
64
+ For **free edit**, prepare only the necessary Business Request field replacements. Do not inspect implementation merely to enrich the request, generate backlog or require another full business interview. Validate required field values without inventing missing dates or ratings. If Azure itself rejects an update for missing required data, explain the actual requirement and collect that input.
65
+
66
+ For **cascade**, read the linked Features and their PBIs, including current states, acceptance criteria, dependencies and Related Business Requests. Map each changed need, rule, constraint, deliverable or approval to the affected items. Search the existing backlog before creating replacements or additions. Account for these outcomes:
67
+
68
+ - An existing Feature/PBI already covers the revised request: preserve it and any valid coverage link.
69
+ - An existing Feature needs extension or correction: revise its complete description, scope and acceptance criteria together with affected PBIs. Changing child PBIs alone is insufficient.
70
+ - A new capability or deliverable is required: create the missing Feature and functional PBIs, reusing the appropriate Epic. Creating a new Feature can remain part of the same Business Request revision.
71
+ - Part of a Feature is no longer requested: remove that portion from the relevant criteria and PBIs while retaining the rest.
72
+ - An entire Feature no longer serves this Business Request: remove this Business Request's coverage link. Cancel the Feature and obsolete PBIs only when that cancellation is part of the agreed change and the effect on any other Business Request has been explicitly addressed.
73
+
74
+ Use the agreed functional model: Epic as thematic area; Feature as functionality or verifiable deliverable; PBI as a portion consultants can manage and verify, with dependencies allowed. Preserve customer-imposed constraints and approval prerequisites. Do not introduce technical tasks, estimates or sprint planning.
75
+
76
+ **Done when:** every added, changed, removed and preserved part maps to Business Request fields or to affected Features and PBIs.
77
+
78
+ ## 3. Resolve shared impact explicitly
79
+
80
+ A Feature is shared when another Business Request also references it, including a Business Request in a terminal state. Sharing matters even when the proposed change is only to a child PBI or to a coverage link. An existing Feature being reused for this Business Request may become shared through the new link.
81
+
82
+ For every affected shared Feature, show:
83
+
84
+ - its title and ID, the other linked Business Requests and their relevant needs;
85
+ - the exact proposed change or removal, including child changes and any derived-rating change;
86
+ - what remains covered and what would change or become uncovered for each other request;
87
+ - appropriate alternatives, such as preserving the shared Feature and detaching this Business Request, or creating a separate Feature for the revised need.
88
+
89
+ Obtain explicit feedback on how to proceed with that specific impact. A general instruction to update the Business Request, silence, or the fact that the Feature is New is not feedback on shared scope. Do not write the Business Request first while this decision is pending. Reuse a decision already explicitly given for the same impact; do not repeatedly ask for it.
90
+
91
+ If another Business Request still needs the existing work, removing it from the current Business Request normally means detaching the current link while preserving that work. A global change or cancellation of a shared Feature requires feedback that explicitly acknowledges its consequences for the other Business Requests. Leave their fields and states unchanged and report any resulting uncovered needs.
92
+
93
+ Record the decision in the local review record alongside the proposed fields and the relevant item revisions. If the proposal or affected Business Request set changes, the earlier decision does not automatically authorize the new impact.
94
+
95
+ **Done when:** every affected shared Feature has explicit user feedback in the local review record.
96
+
97
+ ## 4. Prepare the complete change set
98
+
99
+ Keep a local review record containing the initial eligibility result, requested delta, before/after fields, creations, link additions/removals, cancellations, projected rating effects, shared decisions and revisions. This record is not an `ado.py apply` plan; use the supported files and commands in `references/operations.md`.
100
+
101
+ For a cascade, show a concise account of the whole change set before applying any part. Use the user's existing authorization where it already covers the exact operations. Explicitly settle shared impact and any newly introduced choices. Do not substitute a generic approval of the Business Request for a shared-Feature decision.
102
+
103
+ Run the impact check with every existing Feature/PBI that will be affected. Include existing parents of new PBIs, newly reused Features, link removals/additions and Features whose derived ratings will change. Do not limit the check to items whose title or description changes.
104
+
105
+ ```bash
106
+ python3 <ado> revision-check <Business Request ID> --touch <affected IDs>
107
+ ```
108
+
109
+ If the only remaining blockers are shared Features and the user has given the required feedback, repeat with `--shared-approved <Feature IDs>` for those exact decisions. Never supply this flag merely to make the check pass. It cannot override a disallowed lifecycle state.
110
+
111
+ Preview updates and link removals with their reviewed revisions. Validate creation plans before writes where possible. If Business Request ratings themselves change, preview the final derived Feature ratings using the revised values and final link set; validation against the current Business Request alone does not represent that future state. Preserve the existing maxima and state-freezing rules. Source BusinessValue and Urgency remain explicit business judgments, not estimates made by the agent.
112
+
113
+ **Done when:** `revision-check --touch` passes for the complete change set, and every write has a preview.
114
+
115
+ ## 5. Apply and verify
116
+
117
+ Immediately before the first write, repeat eligibility and impact checks and compare the Business Request, Feature, PBI and sharing snapshots with the reviewed versions. Reconcile unexpected changes before applying. Use `--expected-rev` on existing-item updates and relationship removals. Do not replace an expected revision with the latest number just to bypass a conflict.
118
+
119
+ For free edit, update only the approved Business Request fields and verify the result. For a cascade, execute the complete agreed plan using the sequence in `references/operations.md`, retaining new IDs and completed-operation results. Related links and rating reconciliation can advance item revisions; recognize only verified changes from this same approved operation when updating the local record.
120
+
121
+ The operations are not a cross-item transaction. A failed preflight causes zero writes; a runtime failure after application begins may leave a partial result. Stop dependent writes, report what succeeded and what remains, and inspect before retrying. Do not recreate successful items or blindly roll back work that may have changed meanwhile.
122
+
123
+ Re-read affected items and verify revised content, hierarchy, valid coverage links, cancellations and ratings. Return the Business Request URL, a concise account of what changed, created/updated/removed-from-scope items, and any explicitly accepted impact on shared Features. For a preflight block before application, identify the reason and confirm that this workflow applied no changes. If a blocker appears after writes began, report the actual partial result instead.
124
+
125
+ **Done when:** the user has the Business Request URL and the account of what changed, or the exact partial result.