@collective-intelligence/backlog 0.2.2 → 0.2.4

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
@@ -0,0 +1,361 @@
1
+ #!/usr/bin/env python3
2
+ """Render and check a Client Skill Set: the Human Backlog skills of one client.
3
+
4
+ Fills the Skill Templates in ../references/templates/ from one Client Profile and writes the
5
+ Client Skill Set to a folder outside every skills directory. Every command prints JSON on stdout;
6
+ errors go to stderr as {"error": ...} with exit code 1.
7
+
8
+ Client Profile: --profile FILE (one JSON object), else "humanBacklog.profile" in the nearest
9
+ .devpunks/settings.json above the working directory. Keys: client.name, language.code,
10
+ language.name and skills (required); types, fields, ratings and sprint (optional, as in ado.py).
11
+ The Human Backlog Config (projectUrl, tenant, ...) resolves as in ado.py.
12
+
13
+ Commands
14
+ render [--profile FILE] [--out DIR] write the Client Skill Set; DIR must be empty or absent and
15
+ outside every skills directory (default: a new temp dir).
16
+ Prints {"out", "skills", "slots": [{"file", "slot"}]}; the
17
+ agent fills each {{slot:<name>}} line, then runs check.
18
+ check DIR refuse (a JSON list of problems, exit 1) any {{ left, a SKILL.md
19
+ whose name differs from its folder or has no description, a
20
+ missing dependency, an unquoted description that is not plain
21
+ YAML, or a missing human-backlog-ado, config.json, README.md or
22
+ RENDER.json (the template and profile hashes of the render).
23
+ Prints {"status": "ok"} otherwise.
24
+ """
25
+ import argparse
26
+ import hashlib
27
+ import importlib.util
28
+ import json
29
+ import os
30
+ import re
31
+ import sys
32
+ import tempfile
33
+
34
+ # No bytecode: a __pycache__ under skills/ would ship.
35
+ sys.dont_write_bytecode = True
36
+ SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
37
+ _spec = importlib.util.spec_from_file_location("human_backlog_ado", os.path.join(SCRIPT_DIR, "ado.py"))
38
+ ado = importlib.util.module_from_spec(_spec)
39
+ _spec.loader.exec_module(ado)
40
+
41
+ ADO_SCRIPT = os.path.join(SCRIPT_DIR, "ado.py")
42
+ TEMPLATES = os.path.join(os.path.dirname(SCRIPT_DIR), "references", "templates")
43
+ HELPER = "human-backlog-ado"
44
+ # Every client skill and the skills it hands work to, read from the templates: a selected skill
45
+ # brings each one. analyze-business-request reads Business Requests that create-business-request
46
+ # writes; update-business-request also reuses analyze-business-request's plan format; create-bug
47
+ # sends a new capability to create-business-request.
48
+ NEEDS = {
49
+ "create-business-request": (),
50
+ "analyze-business-request": ("create-business-request",),
51
+ "update-business-request": ("create-business-request", "analyze-business-request"),
52
+ "plan-sprint": (),
53
+ "create-bug": ("create-business-request",),
54
+ }
55
+ PROFILE_KEYS = ("client", "language", "skills", *ado.MAPPING_SECTIONS)
56
+ REQUIRED = {"client": ("name",), "language": ("code", "name")}
57
+ AGENT_DIRS = {".agents", ".claude", ".cursor", ".opencode", ".codex"}
58
+ PLACEHOLDER = re.compile(r"\{\{(.*?)\}\}")
59
+ SLOT = re.compile(r"^\s*\{\{slot:([a-z0-9]+(?:-[a-z0-9]+)*)\}\}\s*$")
60
+ CONFIG_ENTRY = f"{HELPER}/scripts/config.json"
61
+ # What one render was made from; eject checks it and replaces it with MANIFEST.json.
62
+ RENDER_ENTRY = "RENDER.json"
63
+ # A plain YAML scalar that starts with one of these, or holds ": " or " #", is not plain text.
64
+ YAML_INDICATORS = tuple("-?:,[]{}#&*!|>'\"%@`")
65
+ README = """\
66
+ # Human Backlog skills for {client}
67
+
68
+ These agent skills let business users of {client} work in the Human Backlog in Azure DevOps:
69
+ {skills}.
70
+
71
+ ## Install
72
+
73
+ 1. Copy every folder beside this README into the agent skills directory of the repository, for
74
+ example `.agents/skills/` or `.claude/skills/`. Keep the folders side by side: each skill runs
75
+ `../human-backlog-ado/scripts/ado.py`.
76
+ 2. Install Python 3 and the Azure CLI on each user's machine.
77
+ 3. Each user signs in once: `az login --tenant {tenant}`.
78
+ 4. Prove the connection: `python3 human-backlog-ado/scripts/ado.py doctor` prints `"status": "ready"`.
79
+
80
+ `human-backlog-ado/scripts/config.json` names the Azure DevOps project, the tenant and the
81
+ client's names for work item types and fields. Do not edit the skill files; ask for a new set.
82
+ """
83
+
84
+
85
+ def die(msg):
86
+ ado.die(msg)
87
+
88
+
89
+ def is_text(value):
90
+ return isinstance(value, str) and value.strip() != "" and "\n" not in value and "\r" not in value
91
+
92
+
93
+ def profile_sha256(profile):
94
+ """sha256 of the Client Profile as sorted, compact JSON."""
95
+ canonical = json.dumps(profile, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
96
+ return hashlib.sha256(canonical.encode()).hexdigest()
97
+
98
+
99
+ def quote_description(text):
100
+ """The rendered SKILL.md with its frontmatter description as one double-quoted YAML scalar."""
101
+ lines = text.split("\n")
102
+ for i, line in enumerate(lines[1:], 1):
103
+ if line.strip() == "---":
104
+ break
105
+ if line.startswith("description:"):
106
+ value = line[len("description:"):].strip()
107
+ if not value.startswith('"'):
108
+ lines[i] = "description: " + json.dumps(value, ensure_ascii=False)
109
+ return "\n".join(lines)
110
+
111
+
112
+ def profile_problems(profile):
113
+ """Every problem of a Client Profile, with the key path it concerns."""
114
+ if not isinstance(profile, dict):
115
+ return ["The Client Profile must be a JSON object."]
116
+ found = [f"Unknown key profile.{key}." for key in profile if key not in PROFILE_KEYS]
117
+ for key, names in REQUIRED.items():
118
+ value = profile.get(key)
119
+ if value is None:
120
+ found += [f"Missing required key profile.{key}.{name}." for name in names]
121
+ continue
122
+ if not isinstance(value, dict):
123
+ found.append(f"profile.{key} must be a JSON object.")
124
+ continue
125
+ found += [f"Unknown key profile.{key}.{name}." for name in value if name not in names]
126
+ for name in names:
127
+ if name not in value:
128
+ found.append(f"Missing required key profile.{key}.{name}.")
129
+ elif not is_text(value[name]):
130
+ found.append(f"profile.{key}.{name} must be a non-empty string.")
131
+ skills = profile.get("skills")
132
+ if skills is None:
133
+ found.append("Missing required key profile.skills.")
134
+ elif not isinstance(skills, list) or not skills:
135
+ found.append(f"profile.skills must be a non-empty list of skill names: {', '.join(NEEDS)}.")
136
+ else:
137
+ for skill in skills:
138
+ if skill == HELPER:
139
+ found.append(f"profile.skills must not list {HELPER}: it is always rendered.")
140
+ elif not isinstance(skill, str) or skill not in NEEDS:
141
+ found.append(f"Unknown skill {skill!r} in profile.skills; use: {', '.join(NEEDS)}.")
142
+ if len(set(map(str, skills))) != len(skills):
143
+ found.append("profile.skills lists a skill twice.")
144
+ sections = {key: profile[key] for key in ado.MAPPING_SECTIONS if key in profile}
145
+ return found + ado.mapping_problems(sections, {key: f"profile.{key}" for key in ado.MAPPING_SECTIONS})
146
+
147
+
148
+ def closure(selected):
149
+ """The selected skills and every skill they need, transitively."""
150
+ found, pending = set(), list(selected)
151
+ while pending:
152
+ skill = pending.pop()
153
+ if skill not in found:
154
+ found.add(skill)
155
+ pending.extend(NEEDS[skill])
156
+ return found
157
+
158
+
159
+ def rendered_skills(selected):
160
+ """Sorted folder names of the Client Skill Set for these selected skills."""
161
+ return sorted(closure(selected) | {HELPER})
162
+
163
+
164
+ def values(profile):
165
+ """The structured placeholder values of a valid Client Profile."""
166
+ types = {**ado.TYPE_NAMES, **profile.get("types", {})}
167
+ ratings = {**ado.RATINGS, **profile.get("ratings", {})}
168
+ sprint = {**ado.SPRINT, **profile.get("sprint", {})}
169
+ return {"client.name": profile["client"]["name"], "language.name": profile["language"]["name"],
170
+ "language.code": profile["language"]["code"],
171
+ **{f"types.{key}": name for key, name in types.items()},
172
+ "ratings.min": str(ratings["min"]), "ratings.max": str(ratings["max"]),
173
+ "sprint.lengthDays": str(sprint["lengthDays"])}
174
+
175
+
176
+ def config_bytes(config, profile):
177
+ """config.json of the Client Skill Set: the Config keys, then the mappings, ratings and sprint."""
178
+ document = {key: config[key] for key in ado.CONFIG_ENV if config.get(key)}
179
+ document["mappings"] = {"types": {**ado.TYPE_NAMES, **profile.get("types", {})},
180
+ "fields": dict(sorted(profile.get("fields", {}).items()))}
181
+ document["ratings"] = {**ado.RATINGS, **profile.get("ratings", {})}
182
+ document["sprint"] = {**ado.SPRINT, **profile.get("sprint", {})}
183
+ return (json.dumps(document, indent=2, ensure_ascii=False) + "\n").encode()
184
+
185
+
186
+ def fill(text, known, where):
187
+ """(filled text, slot names, problems): known keys replaced, slot lines kept, anything else refused."""
188
+ lines, slots, problems = [], [], []
189
+ for number, line in enumerate(text.split("\n"), 1):
190
+ slot = SLOT.match(line)
191
+ if slot:
192
+ slots.append(slot.group(1))
193
+ lines.append(line)
194
+ continue
195
+ for key in PLACEHOLDER.findall(line):
196
+ if key not in known:
197
+ hint = "a slot must be the whole line" if key.startswith("slot:") else "unknown placeholder"
198
+ problems.append(f"{where}:{number}: {{{{{key}}}}}: {hint}.")
199
+ lines.append(PLACEHOLDER.sub(lambda m: known.get(m.group(1), m.group(0)), line))
200
+ return "\n".join(lines), slots, problems
201
+
202
+
203
+ def in_skills_dir(path):
204
+ parts = os.path.realpath(path).split(os.sep)
205
+ return any(part == "skills" and parts[i - 1] in AGENT_DIRS for i, part in enumerate(parts) if i)
206
+
207
+
208
+ def render(profile, config, out=None):
209
+ """Write the Client Skill Set of `profile` to `out`; return the render report."""
210
+ problems = profile_problems(profile)
211
+ if problems:
212
+ die("The Client Profile is not valid:\n- " + "\n- ".join(problems))
213
+ if out is not None:
214
+ if in_skills_dir(out):
215
+ die(f"{out} is inside a skills directory; render the Client Skill Set outside every skills directory.")
216
+ if os.path.exists(out) and (not os.path.isdir(out) or os.listdir(out)):
217
+ die(f"{out} is not an empty directory; choose an empty or new one.")
218
+ known = values(profile)
219
+ skills = rendered_skills(profile["skills"])
220
+ files, slots, problems = {}, [], []
221
+ for skill in skills:
222
+ folder = os.path.join(TEMPLATES, skill)
223
+ if not os.path.isdir(folder):
224
+ die(f"The Skill Template {skill} is missing from {TEMPLATES}; reinstall the generator.")
225
+ for directory, dirs, names in os.walk(folder):
226
+ dirs.sort()
227
+ for name in sorted(names):
228
+ source = os.path.join(directory, name)
229
+ rel = os.path.relpath(source, TEMPLATES).replace(os.sep, "/")
230
+ target = rel.removesuffix(".tmpl")
231
+ with open(source, encoding="utf-8") as fh:
232
+ text, found, wrong = fill(fh.read(), known, rel)
233
+ if target.endswith("/SKILL.md"):
234
+ text = quote_description(text)
235
+ files[target] = text.encode()
236
+ slots += [{"file": target, "slot": slot} for slot in found]
237
+ problems += wrong
238
+ if problems:
239
+ die("The Skill Templates hold placeholders that render cannot fill:\n- " + "\n- ".join(problems))
240
+ with open(ADO_SCRIPT, "rb") as fh:
241
+ files[f"{HELPER}/scripts/ado.py"] = fh.read()
242
+ files[CONFIG_ENTRY] = config_bytes(config, profile)
243
+ files[RENDER_ENTRY] = (json.dumps({"templateTreeSha256": ado.tree_sha256(ado.tree_files(TEMPLATES)),
244
+ "profileSha256": profile_sha256(profile)}, indent=2) + "\n").encode()
245
+ client_skills = [skill for skill in skills if skill != HELPER]
246
+ files["README.md"] = README.format(client=profile["client"]["name"], tenant=config["tenant"],
247
+ skills=", ".join(f"`{skill}`" for skill in client_skills)).encode()
248
+ out = out or tempfile.mkdtemp(prefix="human-backlog-")
249
+ try:
250
+ for rel, data in sorted(files.items()):
251
+ path = os.path.join(out, *rel.split("/"))
252
+ os.makedirs(os.path.dirname(path), exist_ok=True)
253
+ with open(path, "wb") as fh:
254
+ fh.write(data)
255
+ except OSError as e:
256
+ die(f"Cannot write the Client Skill Set to {out}: {e}")
257
+ return {"out": os.path.abspath(out), "skills": skills, "slots": sorted(slots, key=lambda s: (s["file"], s["slot"]))}
258
+
259
+
260
+ def frontmatter(path, raw=False):
261
+ """The top-level keys of a SKILL.md frontmatter, or None without one; raw keeps each value as written."""
262
+ with open(path, encoding="utf-8") as fh:
263
+ lines = fh.read().split("\n")
264
+ if not lines or lines[0].strip() != "---" or "---" not in (line.strip() for line in lines[1:]):
265
+ return None
266
+ keys = {}
267
+ for line in lines[1:]:
268
+ if line.strip() == "---":
269
+ return keys
270
+ match = re.match(r"^([A-Za-z0-9_-]+):\s*(.*)$", line)
271
+ if match:
272
+ value = match.group(2).strip()
273
+ keys[match.group(1)] = value if raw else value.strip("'\"")
274
+ return keys
275
+
276
+
277
+ def check_problems(directory):
278
+ """Every reason why `directory` is not a complete Client Skill Set; empty when it is one."""
279
+ if not os.path.isdir(directory):
280
+ return [f"{directory} is not a directory."]
281
+ entries = sorted(os.listdir(directory))
282
+ skills = [name for name in entries if os.path.isdir(os.path.join(directory, name))]
283
+ found = []
284
+ found += [f"{name} is missing." for name in ("README.md", RENDER_ENTRY) if name not in entries]
285
+ if HELPER not in skills:
286
+ found.append(f"{HELPER} is missing.")
287
+ else:
288
+ found += [f"{rel} is missing." for rel in (f"{HELPER}/scripts/ado.py", CONFIG_ENTRY)
289
+ if not os.path.isfile(os.path.join(directory, *rel.split("/")))]
290
+ if not [skill for skill in skills if skill != HELPER]:
291
+ found.append(f"No client skill: a Client Skill Set holds at least one skill beside {HELPER}.")
292
+ for skill in skills:
293
+ path = os.path.join(directory, skill, "SKILL.md")
294
+ keys = frontmatter(path) if os.path.isfile(path) else None
295
+ if keys is None:
296
+ found.append(f"{skill}/SKILL.md is missing or has no frontmatter.")
297
+ else:
298
+ if keys.get("name") != skill:
299
+ found.append(f"{skill}/SKILL.md: frontmatter name {keys.get('name')!r} differs from its folder.")
300
+ if not keys.get("description"):
301
+ found.append(f"{skill}/SKILL.md: frontmatter has no description.")
302
+ else:
303
+ raw = frontmatter(path, raw=True)["description"]
304
+ if not raw.startswith('"') and (raw.startswith(YAML_INDICATORS) or ": " in raw or " #" in raw):
305
+ found.append(f"{skill}/SKILL.md: frontmatter description is not valid plain YAML; quote it.")
306
+ found += [f"{skill} needs {need}, which is missing." for need in NEEDS.get(skill, ()) if need not in skills]
307
+ for root, dirs, names in os.walk(directory):
308
+ dirs.sort()
309
+ for name in sorted(names):
310
+ path = os.path.join(root, name)
311
+ rel = os.path.relpath(path, directory).replace(os.sep, "/")
312
+ if rel == f"{HELPER}/scripts/ado.py":
313
+ continue # The helper's own code, copied byte for byte.
314
+ try:
315
+ with open(path, encoding="utf-8") as fh:
316
+ lines = fh.read().split("\n")
317
+ except (OSError, UnicodeDecodeError):
318
+ continue
319
+ found += [f"{rel}:{number}: placeholder left: {line.strip()}"
320
+ for number, line in enumerate(lines, 1) if "{{" in line]
321
+ return found
322
+
323
+
324
+ def load_profile(path):
325
+ if path:
326
+ return ado.load_json(path)
327
+ profile = ado.nearest_settings().get("profile")
328
+ if profile is None:
329
+ die("No Client Profile: pass --profile FILE, or save humanBacklog.profile in the nearest .devpunks/settings.json.")
330
+ return profile
331
+
332
+
333
+ def cmd_render(a):
334
+ profile = load_profile(a.profile)
335
+ ado.out(render(profile, ado.load_config(), a.out))
336
+
337
+
338
+ def cmd_check(a):
339
+ problems = check_problems(a.dir)
340
+ if problems:
341
+ print(json.dumps(problems, indent=2, ensure_ascii=False))
342
+ raise SystemExit(1)
343
+ ado.out({"status": "ok"})
344
+
345
+
346
+ def main():
347
+ p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
348
+ sub = p.add_subparsers(dest="cmd", required=True)
349
+ s = sub.add_parser("render", help="write the Client Skill Set of a Client Profile")
350
+ s.add_argument("--profile", metavar="FILE", help="Client Profile JSON; default: humanBacklog.profile in .devpunks/settings.json")
351
+ s.add_argument("--out", metavar="DIR", help="empty or new directory outside every skills directory; default: a new temp dir")
352
+ s.set_defaults(fn=cmd_render)
353
+ s = sub.add_parser("check", help="refuse an incomplete Client Skill Set")
354
+ s.add_argument("dir", metavar="DIR")
355
+ s.set_defaults(fn=cmd_check)
356
+ a = p.parse_args()
357
+ a.fn(a)
358
+
359
+
360
+ if __name__ == "__main__":
361
+ main()
@@ -1,83 +0,0 @@
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.
@@ -1,26 +0,0 @@
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.