Heritage Community Hub — Project Management Guide

Overview

Work tracking for Heritage Community Hub runs entirely in Azure DevOps (ADO) Boards. Code and pull requests live on GitHub (Heritage-Virginia org); every commit and PR that addresses a work item must include AB#<id> so the two systems stay linked.

Tool	Purpose
ADO Boards — dev.azure.com/hybridcloudsolutions	Single source of truth for all work items
GitHub — github.com/Heritage-Virginia/heritage-community-hub	Code hosting, pull requests, CI/CD
GitHub Issues	Public intake + visibility mirror only — not authoritative

---

ADO project

• Organization: https://dev.azure.com/hybridcloudsolutions
• Project name: Heritage Community Hub
• Process template: Agile (Epic → Feature → User Story → Task)

---

Work item hierarchy

Epic
└── Feature
    └── User Story
        └── Task

Type	Use when
Epic	A large initiative spanning multiple sprints or a full delivery phase (e.g., "Build Platform" AB#3074, "Deliver Community Calendar and Announcements" AB#3075).
Feature	A deliverable with a defined outcome, completable within one sprint cycle. Has a single owner.
User Story	A single unit of work tied to one area of the platform. Completable in one sprint.
Bug	A defect with reproducible steps, expected vs. actual behaviour, and severity.
Task	Sub-work inside a Story. Time-boxed, no Acceptance Criteria required. Not synced to GitHub Issues.

Classification rules

• If it spans more than one sprint → split into a Feature with child Stories.
• If it is a single discrete action (update a file, run a script) → Task.
• If it produces a broken or wrong result → Bug, not Story.
• If it came in via a GitHub Issue → User Story (after triage).

---

Title format

All work item titles start with a verb and follow the pattern:

[scope] Verb-first concise title

• [scope] is required for cross-repo items; omit for items scoped to this project only.
• Maximum 120 characters. No trailing punctuation.
• Good: Define auth provider for end-user login
• Good: [cross-repo] Add shared API-client package
• Bad: User authentication (noun phrase, no verb)
• Bad: Fix the thing in the calendar that breaks (vague)

---

Acceptance Criteria

Acceptance Criteria is required on every item except Tasks. An item is not Done until every criterion is met and verified.

Type	Minimum criteria
Epic	3
Feature	3
User Story	3
Bug	2 (repro confirmed + fix verified)
Task	Not required

Each criterion must be specific and testable — a person must be able to verify it by reading output, checking state, or running a command.

---

Priority

Priority	Meaning
1	Platform broken right now or security incident. Drop everything.
2	Blocks committed sprint work. No workaround. Fix same day or within sprint.
3	Planned sprint work. Normal cadence. (default)
4	Backlog. Valuable but not yet scheduled.

All new items start at Priority 3 unless there is a specific reason to change it.

---

Iterations (sprints)

Iterations are named YYYY-Q<n>-S<m>:

Segment	Rule
YYYY	Four-digit year
Q<n>	Quarter (Q1–Q4)
S<m>	Sprint within the quarter (S1–S6; 2-week sprints, 6 per quarter)

Examples: 2026-Q3-S1, 2026-Q3-S2, 2026-Q4-S1

Sprint backlog is locked at sprint start. Only Priority 1 or Priority 2 items may be added mid-sprint. Unscheduled backlog items stay at the project root iteration — never create a fake sprint to hold them.

---

Area paths

Area paths for this project (as provisioned in ADO; depth capped at 2):

Area path	Use for
Heritage Community Hub\Platform	Auth, RBAC, API, observability, IaC, shared packages, web shell, PM/process, docs/ADRs
Heritage Community Hub\Web	React web client, portal surfaces, design system, shared UI
Heritage Community Hub\Mobile	React Native / Expo iOS + Android apps
Heritage Community Hub\Homeschool	Parent/student account flows, Resource Library, High School Program
Heritage Community Hub\Marketplace	Member listings, vendor/business directory
Heritage Community Hub\Media	Sermons & Music Hub, member-posted media, content library

Calendar, Announcements, Messaging, and project-management work attach to \Platform (or the most specific feature area) plus the relevant tag — there is no separate \Calendar or \Documentation area path. Do not create new area paths without updating this table and the work-items standard.

---

Tags

Apply tags from the vocabulary below. Multiple tags may be applied to one item.

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

---

Delivery roadmap — priority order

Each phase is owned by an ADO Epic; do not advance a phase until its definition of done is met. This is the revised priority order (the canonical sequence in pmo/platform-strategy.md) — the platform is first, the iOS app second, then content/engagement features, then Android, then the rest.

#	Phase	ADO Epic
0	Decide ✅ COMPLETE — ADRs 0001-0024 all Accepted	AB#3154 (Closed)
1	Platform — foundation + identity, RBAC, member features, signups, family portal	AB#3074
2	Apple (iOS) app	AB#3077
3	Sermons & Music Hub	AB#3137
4	Community Calendar & Announcements	AB#3075
5	Messaging & Notifications	AB#3138
6	Google (Android) app	AB#3139
7	Additional features — Small Groups, Homeschool (two tiers), Marketplace, member-posted media	AB#3076
7	Signature features — Pony Express, Ride Share, Sister Community	AB#3078

---

GitHub Issues — intake mirror

GitHub Issues are a public intake surface and visibility mirror only.

• External contributors open GitHub Issues. Internal work is filed directly in ADO.
• When a GitHub Issue is opened, a corresponding ADO User Story is created and the issue is labeled ado-tracked.
• When the ADO item changes state, the linked GitHub Issue is updated automatically:

ADO state	GitHub Issue action
Active / In Progress	Label in-progress added
Resolved	Label resolved added, resolution comment added
Closed	Issue closed
Won't Fix	Issue closed with label wont-fix

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

---

Commit and PR linking

Every commit and PR description that touches a work item must include AB#<id>. ADO automatically creates a link between the work item and the commit or PR.

feat(calendar): add recurring event support AB#47

fix(auth): handle expired social login tokens AB#52

docs(adr): record auth provider decision AB#18

Commit format: type(scope): short description AB#<id>

Types: feat, fix, docs, chore, refactor, test

---

Dependencies

Express dependencies between work items using ADO link types — not just text in the description.

Link type	When to use
Predecessor	This item must complete before the linked item can start.
Successor	This item cannot start until the linked item is done.
Related	Items share context but have no strict ordering.
Child / Parent	Hierarchical decomposition within the Epic → Feature → Story → Task chain.

---

Closing criteria

A work item may only be moved to Closed when:

1. All Acceptance Criteria are met and verified.
2. Code or doc changes are committed and the pipeline has passed.
3. The linked GitHub Issue (if any) has been updated with a status comment.
4. Any follow-up work items have been created.

Moving an item to Closed without meeting these criteria is a standards violation.

---

Sprint process

Sprint planning

1. Review items in the backlog — confirm priority, estimates, and dependencies are current.
2. Pull Priority 3 items into the sprint up to team capacity.
3. Assign each item to the sprint iteration (YYYY-Q<n>-S<m>).
4. Move items to Active state.

Mid-sprint check-in

1. Review Active items — identify blockers.
2. Escalate Priority 2 blockers immediately.
3. Do not add new scope unless Priority 1 or 2.

Sprint review / retrospective

1. Demo completed stories.
2. Move incomplete items to the next sprint and document why in the comments field.
3. Close completed items after verifying all AC.
4. Update the phase roadmap if a phase gate was reached.

---

az boards CLI — common operations

All work item operations can be run using the Azure CLI with the az boards extension. Set your organization and project once per session:

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

Create a User Story:

az boards work-item create `
  --type "User Story" `
  --title "Define invitation-code registration flow" `
  --assigned-to "kris@hybridsolutions.cloud" `
  --area "Heritage Community Hub\Platform" `
  --iteration "Heritage Community Hub\2026-Q3-S1" `
  --fields "Priority=3" "Tags=identity;platform"

Update state:

az boards work-item update --id <id> --state Active

Add a comment:

az boards work-item update --id <id> --discussion "Blocked on auth provider ADR — will resume after Phase 0."

Show a work item:

az boards work-item show --id <id>

Query work items in the current sprint:

az boards query --wiql "SELECT [System.Id],[System.Title],[System.State] FROM WorkItems WHERE [System.TeamProject]='Heritage Community Hub' AND [System.IterationPath]='Heritage Community Hub\2026-Q3-S1'"

---

New work item checklist

Before saving a new item, verify:

• [ ] 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 count by type)
• [ ] Type is correct (Epic / Feature / Story / Bug / Task)
• [ ] Priority set (1–4; default 3)
• [ ] At least one tag applied
• [ ] Area path is correct
• [ ] Iteration assigned if Active; root if backlog
• [ ] Dependencies linked (Predecessor / Successor / Related)
• [ ] AB#<id> referenced in any associated commit or PR