Heritage Community Hub — ADO Project Setup

This document describes the work tracking model for Heritage Community Hub: how the ADO project is structured, how work item types are used, and how GitHub Issues feed into ADO as an intake surface.

---

Project coordinates

Field	Value
ADO org	https://dev.azure.com/hybridcloudsolutions
ADO project	Heritage Community Hub
Process template	Agile
GitHub repo	github.com/Heritage-Virginia/heritage-community-hub
GitHub org	Heritage-Virginia

One ADO project per repo is the platform standard. Work items in ADO always belong to exactly one project. Cross-repo work is modeled by linking items across projects.

---

Work item types

Epic

Use for large initiatives that span multiple sprints or align to a delivery phase. An Epic has a measurable outcome at the platform level.

• Minimum 3 Acceptance Criteria.
• Typically maps to a delivery phase in the revised priority order (each phase = one ADO Epic).
• Contains child Features.

Example titles (real Epics):

• Build Platform (AB#3074)
• Deliver iOS (Apple) App (AB#3077)
• Deliver Community Calendar and Announcements (AB#3075)

Feature

Use for a deliverable with a defined outcome, completable within one sprint cycle (up to 4 weeks). A Feature has a single owner and contains child User Stories.

• Minimum 3 Acceptance Criteria.
• Must map to a parent Epic.

Example titles:

• Define invitation-code registration and minister-approval workflow
• Build community calendar event creation and RSVP API

User Story

Use for a single unit of work tied to one area of the platform, completable in one sprint.

• Minimum 3 Acceptance Criteria.
• Must map to a parent Feature.
• This is the type created when a GitHub Issue is triaged.

Example titles:

• Create family-group data model and migration
• Add Apple Sign In to the web login screen

Bug

Use for a defect with reproducible steps. A Bug carries:

• Steps to reproduce.
• Expected behaviour.
• Actual behaviour.
• Severity.

Minimum 2 Acceptance Criteria: (1) repro confirmed, (2) fix verified.

Task

Sub-work inside a Story. Time-boxed. No Acceptance Criteria required. Not synced to GitHub Issues. Tasks are for single discrete actions: update a config file, write a migration, add a unit test.

---

Area paths

Area path	Work that belongs here
Heritage Community Hub\Platform	Auth, RBAC, API, IaC, observability, shared packages, web shell, calendar/announcements/messaging, PM/process, ADRs/docs
Heritage Community Hub\Web	React web client, portal surfaces, design system, shared UI
Heritage Community Hub\Mobile	React Native + Expo, push notifications, app-store pipelines
Heritage Community Hub\Homeschool	Parent/student accounts, Resource Library, High School Program, teacher tools
Heritage Community Hub\Marketplace	Member listings, vendor directory, browse/review flows
Heritage Community Hub\Media	Sermons & Music Hub, member-posted media, content library

Rules:

• These six area paths are the set provisioned in ADO. Depth is capped at 2 levels (project root + one child). Do not create sub-children.
• There is no separate \Calendar, \Project Management, or \Documentation area path — that work attaches to \Platform plus the relevant tag (calendar, docs, etc.).
• Do not create new area paths without updating this table and the work-items standard.

---

Iterations

Pattern: Heritage Community Hub\YYYY-Q<n>-S<m>

• 2-week sprints.
• 6 sprints per quarter (S1–S6).
• Unscheduled backlog items sit at the project root iteration — not in a sprint.
• An item moved to Active must be assigned to a sprint.

See pmo/board-setup-action-plan.md for the PowerShell commands to create iteration nodes.

---

Tags

Tag	Apply when
platform	Cross-cutting platform work
calendar	Calendar feature area
homeschool	Homeschool portal feature area
marketplace	Marketplace feature area
mobile	Mobile app (React Native / Expo)
identity	Auth, RBAC, social login, Key Vault
pipeline	CI/CD, ADO pipeline YAML
docs	Documentation, ADRs, standards
security	Security findings, COPPA, trust & safety
infrastructure	Bicep, Azure resources, IaC
breaking	Change breaks an existing interface
cross-repo	Work spans more than one repo

Apply all tags that are relevant — a work item may carry multiple tags.

---

GitHub Issues as intake

GitHub Issues are the public intake surface only. They are not the source of truth.

How it works

Contributor opens GitHub Issue
        |
        v (automated sync on issue open)
ADO User Story created in "Heritage Community Hub" project
        |
        | Issue labeled "ado-tracked", ADO link added as comment
        v
ADO is the record. Work proceeds in ADO.
        |
        v (automated sync on state change)
GitHub Issue updated with labels + resolution comment

Triage steps for a new GitHub Issue

1. Verify the issue is needs-triage labeled (the sync applies this if it fires before manual triage).
2. Open the auto-created ADO User Story.
3. Set the correct area path, priority, and tags.
4. Assign it to the appropriate Feature (or create a Feature if none exists).
5. Leave the GitHub Issue open and let the sync manage its labels going forward.
6. If the issue is out of scope or a duplicate, set ADO state to Won't Fix — the sync will close the GitHub Issue with the wont-fix label.

Standard GitHub labels

Label	Color	Meaning
ado-tracked	blue	Issue has a linked ADO work item
in-progress	yellow	ADO item is actively being worked
resolved	green	ADO item resolved — pending close
wont-fix	grey	ADO item closed as won't fix
needs-triage	red	Issue received, ADO item not yet created
cross-repo	purple	Affects more than one repo

---

Creating work items via az boards

Set defaults once per session:

az devops configure --defaults `
  organization=https://dev.azure.com/hybridcloudsolutions `
  project="Heritage Community Hub"

Create an Epic

az boards work-item create `
  --type Epic `
  --title "Build Platform" `
  --area "Heritage Community Hub\Platform" `
  --fields "Priority=2" "Tags=platform;identity"

Create a Feature under an Epic

az boards work-item create `
  --type Feature `
  --title "Build minister-approval account onboarding flow" `
  --parent <epic-id> `
  --area "Heritage Community Hub\Platform" `
  --iteration "Heritage Community Hub\2026-Q3-S2" `
  --fields "Priority=2" "Tags=identity;security"

Create a User Story under a Feature

az boards work-item create `
  --type "User Story" `
  --title "Add invitation-code validation to registration endpoint" `
  --parent <feature-id> `
  --area "Heritage Community Hub\Platform" `
  --iteration "Heritage Community Hub\2026-Q3-S2" `
  --assigned-to "kris@hybridsolutions.cloud" `
  --fields "Priority=3" "Tags=identity"

Add Acceptance Criteria to a work item

Acceptance Criteria goes in the Microsoft.VSTS.Common.AcceptanceCriteria field. Use HTML:

$ac = "<ul><li>Given a valid invitation code, when a new user submits registration, then the account is created in Pending state.</li><li>Given an invalid or expired code, then registration is rejected with a descriptive error message.</li><li>All inputs are validated server-side before any DB write occurs.</li></ul>"

az boards work-item update `
  --id <story-id> `
  --fields "Microsoft.VSTS.Common.AcceptanceCriteria=$ac"

Link a parent to a child

az boards work-item relation add `
  --id <child-id> `
  --relation-type "System.LinkTypes.Hierarchy-Reverse" `
  --target-id <parent-id>

Move an item to Active and assign a sprint

az boards work-item update `
  --id <id> `
  --state Active `
  --iteration "Heritage Community Hub\2026-Q3-S2"

---

New work item checklist

Before saving a new work item:

• [ ] Title starts with a verb; [scope] prefix if cross-repo
• [ ] Description answers: what, why now, in scope, out of scope
• [ ] Acceptance Criteria filled in (minimum 3 for Epic/Feature/Story; 2 for Bug)
• [ ] Type is correct (Epic / Feature / Story / Bug / Task)
• [ ] Priority set (1–4; default 3)
• [ ] At least one tag applied
• [ ] Area path is set and correct
• [ ] Iteration assigned if Active; root iteration if backlog
• [ ] Parent linked (Feature has Epic parent; Story has Feature parent; Task has Story parent)
• [ ] Dependencies linked (Predecessor / Successor / Related) where they exist
• [ ] AB#<id> included in any associated commit or PR description