jumpstart-mode 1.1.13 → 1.1.14

package/.github/skills/azure-devops-delivery-builder/references/wiql-and-reporting.md

@@ -0,0 +1,80 @@
+# WIQL And Reporting Guide
+
+Use this reference when the user needs Azure DevOps queries or delivery reporting outputs.
+
+## Useful Query Shapes
+
+### Open MVP Work
+
+```sql
+SELECT
+    [System.Id],
+    [System.WorkItemType],
+    [System.Title],
+    [System.State],
+    [Microsoft.VSTS.Common.Priority]
+FROM WorkItems
+WHERE
+    [System.TeamProject] = @project
+    AND [System.State] <> 'Closed'
+    AND [System.Tags] CONTAINS 'mvp'
+ORDER BY [Microsoft.VSTS.Common.Priority] ASC
+```
+
+### Open Client Dependencies
+
+```sql
+SELECT
+    [System.Id],
+    [System.WorkItemType],
+    [System.Title],
+    [System.State],
+    [System.AssignedTo]
+FROM WorkItems
+WHERE
+    [System.TeamProject] = @project
+    AND [System.State] <> 'Closed'
+    AND [System.Tags] CONTAINS 'client-dependency'
+ORDER BY [System.ChangedDate] DESC
+```
+
+### Open AI Or RAG Work
+
+```sql
+SELECT
+    [System.Id],
+    [System.WorkItemType],
+    [System.Title],
+    [System.State]
+FROM WorkItems
+WHERE
+    [System.TeamProject] = @project
+    AND [System.State] <> 'Closed'
+    AND (
+        [System.Tags] CONTAINS 'rag'
+        OR [System.Tags] CONTAINS 'llm'
+        OR [System.Tags] CONTAINS 'agent'
+    )
+ORDER BY [System.ChangedDate] DESC
+```
+
+## Reporting Shapes
+
+Useful report outputs:
+
+- Sprint readiness report
+- Blocked work report
+- Dependency report
+- Backlog quality report
+- MVP progress summary
+- AI workstream status
+- Pipeline readiness report
+- Scope creep watchlist
+
+## Report Structure
+
+1. Summary numbers
+2. Highest-risk items
+3. Missing dependencies or approvals
+4. Items not ready for sprint planning
+5. Recommended next actions

package/.github/skills/azure-devops-delivery-builder/scripts/generate_azure_devops_csv.py

@@ -0,0 +1,138 @@
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+from typing import TextIO
+
+
+COLUMNS = [
+    "Work Item Type",
+    "Title",
+    "Description",
+    "Acceptance Criteria",
+    "Priority",
+    "Value Area",
+    "Tags",
+    "Area Path",
+    "Iteration Path",
+    "Parent",
+    "Original Estimate",
+    "Remaining Work",
+    "Story Points",
+    "Effort",
+    "Business Value",
+    "Risk",
+    "State",
+    "Assigned To",
+]
+
+KEY_MAP = {
+    "work_item_type": "Work Item Type",
+    "type": "Work Item Type",
+    "title": "Title",
+    "description": "Description",
+    "acceptance_criteria": "Acceptance Criteria",
+    "priority": "Priority",
+    "value_area": "Value Area",
+    "tags": "Tags",
+    "area_path": "Area Path",
+    "iteration_path": "Iteration Path",
+    "parent": "Parent",
+    "original_estimate": "Original Estimate",
+    "remaining_work": "Remaining Work",
+    "story_points": "Story Points",
+    "effort": "Effort",
+    "business_value": "Business Value",
+    "risk": "Risk",
+    "state": "State",
+    "assigned_to": "Assigned To",
+}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Convert structured backlog JSON into Azure DevOps import CSV."
+    )
+    parser.add_argument(
+        "input",
+        help="Path to a JSON file or '-' to read JSON from stdin.",
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        help="Path to write the CSV file. Defaults to stdout.",
+    )
+    return parser.parse_args()
+
+
+def load_input(source: str):
+    if source == "-":
+        return json.load(sys.stdin)
+
+    input_path = Path(source)
+    with input_path.open("r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def extract_items(payload) -> list[dict]:
+    if isinstance(payload, list):
+        return payload
+    if isinstance(payload, dict):
+        if isinstance(payload.get("work_items"), list):
+            return payload["work_items"]
+        if isinstance(payload.get("items"), list):
+            return payload["items"]
+    raise ValueError(
+        "Expected a list of work items or an object containing 'work_items' or 'items'."
+    )
+
+
+def normalize_value(value) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, list):
+        return "; ".join(str(item) for item in value)
+    if isinstance(value, dict):
+        return json.dumps(value, ensure_ascii=True, sort_keys=True)
+    return str(value)
+
+
+def to_row(item: dict) -> dict[str, str]:
+    row = {column: "" for column in COLUMNS}
+    for raw_key, value in item.items():
+        column = KEY_MAP.get(raw_key, raw_key)
+        if column in row:
+            row[column] = normalize_value(value)
+    return row
+
+
+def write_rows(rows: list[dict[str, str]], output_path: str | None) -> None:
+    handle: TextIO
+    if output_path:
+        handle = Path(output_path).open("w", encoding="utf-8", newline="")
+        should_close = True
+    else:
+        handle = sys.stdout
+        should_close = False
+
+    try:
+        writer = csv.DictWriter(handle, fieldnames=COLUMNS)
+        writer.writeheader()
+        writer.writerows(rows)
+    finally:
+        if should_close:
+            handle.close()
+
+
+def main() -> int:
+    args = parse_args()
+    payload = load_input(args.input)
+    items = extract_items(payload)
+    rows = [to_row(item) for item in items]
+    write_rows(rows, args.output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.github/skills/azure-devops-delivery-builder/scripts/smoke_test_csv_tools.py

@@ -0,0 +1,56 @@
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+def run(command: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        command,
+        cwd=cwd,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+
+
+def main() -> int:
+    repo_root = Path(__file__).resolve().parents[4]
+    skill_root = Path(__file__).resolve().parents[1]
+    fixture = skill_root / "examples" / "fixtures" / "backlog-items-smoke.json"
+
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        output_csv = Path(tmp_dir) / "ado-smoke.csv"
+
+        generate_cmd = [
+            "python3",
+            str(skill_root / "scripts" / "generate_azure_devops_csv.py"),
+            str(fixture),
+            "--output",
+            str(output_csv),
+        ]
+        generated = run(generate_cmd, repo_root)
+        if generated.returncode != 0:
+            print("Generate script failed")
+            print(generated.stdout)
+            print(generated.stderr)
+            return 1
+
+        validate_cmd = [
+            "python3",
+            str(skill_root / "scripts" / "validate_azure_boards_backlog.py"),
+            str(output_csv),
+        ]
+        validated = run(validate_cmd, repo_root)
+        if validated.returncode != 0:
+            print("Validate script failed")
+            print(validated.stdout)
+            print(validated.stderr)
+            return 1
+
+        print("CSV tool smoke test passed")
+        print(validated.stdout.strip())
+        return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.github/skills/azure-devops-delivery-builder/scripts/validate_azure_boards_backlog.py

@@ -0,0 +1,105 @@
+import argparse
+import csv
+from pathlib import Path
+from typing import cast
+
+
+REQUIRED_COLUMNS = {
+    "Work Item Type",
+    "Title",
+    "Description",
+    "Acceptance Criteria",
+    "Priority",
+    "Tags",
+    "Area Path",
+    "Iteration Path",
+}
+
+STORY_TYPES = {"User Story", "Product Backlog Item", "Requirement"}
+SUGGESTED_SIGNAL_TAGS = {"ai-pod", "jumpstart", "mvp", "needs-refinement"}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Validate Azure Boards CSV imports for required columns and basic quality issues."
+    )
+    parser.add_argument("csv_path", help="Path to the Azure Boards CSV file.")
+    return parser.parse_args()
+
+
+def load_rows(csv_path: Path) -> tuple[list[dict[str, str]], list[str]]:
+    with csv_path.open("r", encoding="utf-8-sig", newline="") as handle:
+        reader = csv.DictReader(handle)
+        fieldnames = [str(name) for name in (reader.fieldnames or [])]
+        rows = [cast(dict[str, str], row) for row in reader]
+    return rows, fieldnames
+
+
+def find_issues(rows: list[dict[str, str]], fieldnames: list[str]) -> list[str]:
+    issues: list[str] = []
+    missing_columns = sorted(REQUIRED_COLUMNS - set(fieldnames))
+    if missing_columns:
+        issues.append("Missing required columns: " + ", ".join(missing_columns))
+
+    for index, row in enumerate(rows, start=2):
+        item_type = (row.get("Work Item Type") or "").strip()
+        title = (row.get("Title") or "").strip()
+        description = (row.get("Description") or "").strip()
+        acceptance = (row.get("Acceptance Criteria") or "").strip()
+        area_path = (row.get("Area Path") or "").strip()
+        iteration_path = (row.get("Iteration Path") or "").strip()
+        tags = (row.get("Tags") or "").strip()
+
+        if not title:
+            issues.append(f"Row {index}: missing Title")
+        elif len(title.split()) < 2:
+            issues.append(f"Row {index}: title is too vague: '{title}'")
+
+        if not description:
+            issues.append(f"Row {index}: missing Description")
+
+        if item_type in STORY_TYPES and "given" not in acceptance.lower():
+            issues.append(
+                f"Row {index}: {item_type} is missing Given/When/Then-style acceptance criteria"
+            )
+
+        if item_type == "Spike":
+            combined_text = " ".join([title.lower(), description.lower(), acceptance.lower()])
+            if "deliverable" not in combined_text and "decision" not in combined_text:
+                issues.append(f"Row {index}: Spike should name a decision or deliverable")
+
+        if not area_path:
+            issues.append(f"Row {index}: missing Area Path")
+        if not iteration_path:
+            issues.append(f"Row {index}: missing Iteration Path")
+        if not tags:
+            issues.append(f"Row {index}: missing Tags")
+        else:
+            normalized_tags = {tag.strip() for tag in tags.split(";") if tag.strip()}
+            if not normalized_tags.intersection(SUGGESTED_SIGNAL_TAGS):
+                issues.append(
+                    f"Row {index}: tags do not include any planning signal tag such as ai-pod, jumpstart, mvp, or needs-refinement"
+                )
+
+    return issues
+
+
+def main() -> int:
+    args = parse_args()
+    csv_path = Path(args.csv_path)
+    rows, fieldnames = load_rows(csv_path)
+    issues = find_issues(rows, fieldnames)
+
+    if issues:
+        print("Azure Boards backlog validation failed:")
+        for issue in issues:
+            print(f"- {issue}")
+        return 1
+
+    print(f"Azure Boards backlog validation passed for {csv_path}")
+    print(f"Rows checked: {len(rows)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.github/skills/azure-devops-delivery-builder/templates/ado-import-template.csv

@@ -0,0 +1,5 @@
+Work Item Type,Title,Description,Acceptance Criteria,Priority,Tags,Area Path,Iteration Path,Parent,Story Points,Original Estimate,Remaining Work,Business Value,Risk,State,Assigned To
+Epic,[Epic title],[Epic description],[Epic success criteria],1,"ai-pod;jumpstart",[Area Path],[Iteration Path],,, ,,[Business Value],[Risk],New,
+Feature,[Feature title],[Feature description],[Feature acceptance criteria],1,"mvp;integration",[Area Path],[Iteration Path],[Parent epic],,, ,,[Business Value],[Risk],New,
+User Story,[Story title],[Story description],[Story acceptance criteria],2,"backend;ready",[Area Path],[Iteration Path],[Parent feature],5,,,[Business Value],[Risk],New,
+Task,[Task title],[Task description],[Task done criteria],2,"devops;testing",[Area Path],[Iteration Path],[Parent story],,8,8,[Business Value],[Risk],New,

package/.github/skills/azure-devops-delivery-builder/templates/backlog-items-template.json

@@ -0,0 +1,48 @@
+{
+  "work_items": [
+    {
+      "work_item_type": "Epic",
+      "title": "Quote Acceleration Platform",
+      "description": "Create the platform capability for AI-assisted quote intake and review workflows.",
+      "acceptance_criteria": [
+        "Business stakeholders can track intake, review, and approval flow.",
+        "The backlog is traceable to source discovery material."
+      ],
+      "priority": 1,
+      "value_area": "Business",
+      "tags": [
+        "ai-pod",
+        "jumpstart",
+        "mvp"
+      ],
+      "area_path": "AI Pod\\Quote Acceleration",
+      "iteration_path": "AI Pod\\Sprint 0 - Discovery and Setup",
+      "business_value": "Reduce manual RFQ intake effort and improve throughput.",
+      "risk": "Medium",
+      "state": "New"
+    },
+    {
+      "work_item_type": "User Story",
+      "title": "Upload RFQ package",
+      "description": "As a sales operations user, I want to upload an RFQ package so that quote data can be extracted and reviewed.",
+      "acceptance_criteria": [
+        "Given a supported RFQ file, when the user uploads it, then the system stores the file and creates an intake record.",
+        "Given the file fails validation, when the user submits it, then the system returns a clear error and does not create an intake record.",
+        "Given upload succeeds, when extraction begins, then the intake status changes to Processing."
+      ],
+      "priority": 1,
+      "tags": [
+        "backend",
+        "frontend",
+        "mvp"
+      ],
+      "area_path": "AI Pod\\Quote Acceleration",
+      "iteration_path": "AI Pod\\Sprint 1 - Foundation",
+      "parent": "RFQ Intake Automation",
+      "story_points": 5,
+      "business_value": "Creates the intake entry point for the MVP workflow.",
+      "risk": "Medium",
+      "state": "New"
+    }
+  ]
+}

package/.github/skills/azure-devops-delivery-builder/templates/bug-template.md

@@ -0,0 +1,27 @@
+# Bug: [Broken Behavior]
+
+## Problem
+
+[What is broken and who it impacts]
+
+## Expected Behavior
+
+[What should happen]
+
+## Current Behavior
+
+[What happens now]
+
+## Reproduction Notes
+
+1. [Step]
+2. [Step]
+
+## Acceptance Criteria
+
+1. Given [context], when [issue is triggered], then [correct behavior occurs].
+2. Given [failure condition], when [user retries or recovers], then [expected handling occurs].
+
+## Source Traceability
+
+[Incident, bug report, transcript note, or user instruction]

package/.github/skills/azure-devops-delivery-builder/templates/epic-template.md

@@ -0,0 +1,36 @@
+# Epic: [Business Outcome]
+
+## Business Goal
+
+[What business outcome this epic supports.]
+
+## Scope
+
+[What capability area is included.]
+
+## Success Metrics
+
+- [Metric or measurable outcome]
+- [Metric or measurable outcome]
+
+## In Scope
+
+- [Capability]
+- [Capability]
+
+## Out Of Scope
+
+- [Explicit exclusion]
+
+## Features
+
+- [Feature name]
+- [Feature name]
+
+## Dependencies
+
+- [Dependency]
+
+## Source Traceability
+
+[Source document, workshop note, transcript section, or user instruction]

package/.github/skills/azure-devops-delivery-builder/templates/feature-template.md

@@ -0,0 +1,33 @@
+# Feature: [Capability Name]
+
+## Capability Description
+
+[What this feature enables]
+
+## Users Or Systems
+
+[Primary users or systems involved]
+
+## Business Value
+
+[Why this feature matters]
+
+## Child Stories Or PBIs
+
+- [Child item]
+
+## Acceptance Criteria
+
+- [Testable criterion]
+
+## Dependencies
+
+- [Dependency]
+
+## Risks
+
+- [Risk]
+
+## Source Traceability
+
+[Source reference]

package/.github/skills/azure-devops-delivery-builder/templates/spike-template.md

@@ -0,0 +1,26 @@
+# Spike: [Unknown To Validate]
+
+## Objective
+
+[What uncertainty must be resolved]
+
+## Questions To Answer
+
+- [Question]
+- [Question]
+
+## Investigation Approach
+
+[How the team will validate the answer]
+
+## Deliverable
+
+[Design note, recommendation, prototype, estimate, or decision]
+
+## Timebox
+
+[Suggested timebox]
+
+## Decision Needed
+
+[What decision this spike unlocks]

package/.github/skills/azure-devops-delivery-builder/templates/story-pbi-template.md

@@ -0,0 +1,35 @@
+# User Story Or PBI: [Action-Oriented Summary]
+
+## User Story
+
+As a [role], I want [capability], so that [business outcome].
+
+## Background
+
+[Context from source material]
+
+## Acceptance Criteria
+
+1. Given [context], when [action], then [expected result].
+2. Given [context], when [edge case], then [expected handling].
+3. Given [context], when [permission or failure case], then [expected behavior].
+
+## Implementation Notes
+
+[Technical notes, constraints, likely files, API expectations]
+
+## Dependencies
+
+- [Dependency]
+
+## Out Of Scope
+
+- [Explicit exclusion]
+
+## Test Expectations
+
+- [Unit, integration, E2E, or manual validation]
+
+## Source Traceability
+
+[Reference to source document, section, quote, or requirement ID]

package/.github/skills/azure-devops-delivery-builder/templates/task-template.md

@@ -0,0 +1,18 @@
+# Task: [Technical Work]
+
+## Objective
+
+[What needs to be implemented]
+
+## Implementation Notes
+
+[Specific technical details]
+
+## Parent Work Item
+
+[Feature or Story/PBI]
+
+## Done When
+
+- [Completion criterion]
+- [Completion criterion]

package/.github/skills/azure-devops-execution/README.md

@@ -0,0 +1,22 @@
+# Azure DevOps Execution Skill
+
+This skill package performs execution against Azure DevOps after backlog shaping is complete.
+
+## Included Assets
+
+- `SKILL.md`: execution behavior and safety rules
+- `scripts/import_csv_to_ado.py`: create work items from CSV with dry-run mode
+- `scripts/run_wiql.py`: run WIQL and return matching rows
+
+## Quick Start
+
+1. Set environment variables:
+   - `ADO_ORG_URL`
+   - `ADO_PROJECT`
+   - `ADO_PAT`
+2. Dry-run import:
+   - `python ./.github/skills/azure-devops-execution/scripts/import_csv_to_ado.py path/to/ado-import.csv --dry-run`
+3. Live import:
+   - `python ./.github/skills/azure-devops-execution/scripts/import_csv_to_ado.py path/to/ado-import.csv`
+4. Run WIQL:
+   - `python ./.github/skills/azure-devops-execution/scripts/run_wiql.py --wiql-file path/to/query.sql`

package/.github/skills/azure-devops-execution/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: azure-devops-execution
+description: 'Use this skill when the user wants to execute Azure DevOps operations from prepared backlog artifacts, including importing CSV-backed work items, creating work items through Azure DevOps REST, and running WIQL queries for reporting. This skill is execution-focused and should be used after backlog shaping is complete.'
+argument-hint: 'Provide your Azure DevOps organization URL, project, auth method, and whether to run dry-run preview, create work items, or execute WIQL.'
+---
+
+# Azure DevOps Execution
+
+Execute Azure DevOps work from prepared artifacts after backlog shaping is complete.
+
+## Use This Skill When
+
+- The user wants to create Azure Boards work items from structured CSV artifacts.
+- The user wants to run WIQL against Azure DevOps and export results.
+- The user wants a safe dry-run preview before API writes.
+
+## Do Not Use This Skill When
+
+- The backlog still needs decomposition or quality review. Use `azure-devops-delivery-builder` first.
+- The user cannot provide Azure DevOps API access details.
+
+## Environment Requirements
+
+Set these before running scripts:
+
+- `ADO_ORG_URL`: Azure DevOps org URL, for example `https://dev.azure.com/contoso`
+- `ADO_PROJECT`: target Azure DevOps project name
+- `ADO_PAT`: personal access token with Boards read/write permissions
+
+## Script Index
+
+- [import_csv_to_ado.py](./scripts/import_csv_to_ado.py): Import CSV work items to Azure DevOps with dry-run support
+- [run_wiql.py](./scripts/run_wiql.py): Execute WIQL queries and print JSON rows
+
+## Recommended Workflow
+
+1. Shape backlog with `azure-devops-delivery-builder`.
+2. Generate import CSV and validate quality.
+3. Run import script in dry-run mode first.
+4. Run live import after user confirmation.
+5. Run WIQL checks to verify imported items.
+
+## Safety Rules
+
+- Default to `--dry-run` unless the user explicitly asks to write.
+- Never print or echo `ADO_PAT`.
+- Stop on first create failure unless user requests best-effort behavior.
+- Capture summary counts for created, skipped, and failed rows.