VS Code — Azure Boards + Azure Repos Workflow

This guide covers the day-to-day development workflow for Heritage Community Hub using VS Code with the Azure Boards and Azure Repos integrations. Work items live in ADO; code and PRs live on GitHub. Both surfaces are reachable without leaving VS Code.

---

Required extensions

Install these extensions before following this guide.

ADO / Azure extensions

Extension	ID	Purpose
Azure Repos	ms-vscode.azure-repos	Browse and manage Azure Repos directly (optional if code is on GitHub)
Azure Boards	ms-azure-devops.azure-boards	View and update ADO work items from VS Code
Azure CLI Tools	ms-vscode.azurecli	IntelliSense and linting for az CLI scripts in the editor

Install via the Extensions panel (Ctrl+Shift+X) or the CLI:

code --install-extension ms-azure-devops.azure-boards
code --install-extension ms-vscode.azurecli

GitHub extensions (already present)

Extension	ID
GitHub Pull Requests	GitHub.vscode-pull-request-github
GitHub Actions	GitHub.vscode-github-actions

Recommended general extensions

Extension	ID	Purpose
GitLens	eamodio.gitlens	Rich git history, blame, and branch visualization
Git Graph	mhutchie.git-graph	Visual git history with branch lanes
Todo Tree	Gruntfuggly.todo-tree	Surface TODO/FIXME comments across the codebase
ESLint	dbaeumer.vscode-eslint	Real-time lint feedback (required by platform standards)
Prettier	esbenp.prettier-vscode	Format on save

---

Sign in

Sign in to Azure (for ADO and az CLI)

az login

If running headless or on a device without a browser, use device code:

az login --use-device-code

Load HCS environment variables (Key Vault secrets, PATs):

. D:\git\platform\scripts\Load-HCSEnvironment.ps1

Set ADO defaults for the session:

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

Sign in to GitHub (for PRs and GitHub Actions)

In VS Code, open the Command Palette (Ctrl+Shift+P) and run:

GitHub: Sign in to GitHub

Authenticate with your GitHub account when the browser prompt appears.

---

Daily workflow

Morning: check assigned work

In VS Code using Azure Boards extension:

1. Open the Activity Bar — click the Azure Boards icon (or press Ctrl+Shift+P and type Azure Boards: View My Work Items).
2. Review items assigned to you that are In Progress or Active.
3. For an item you are starting today, right-click and select Open in Browser to view its full detail in ADO, then set state to Active if not already set.

Via az CLI:

# List your Active and New items
az boards query --wiql "SELECT [System.Id],[System.Title],[System.State],[System.IterationPath] FROM WorkItems WHERE [System.AssignedTo]='kris@hybridsolutions.cloud' AND [System.State] IN ('New','Active') ORDER BY [System.Priority]"

---

Starting work on a User Story

1. Confirm the ADO User Story has a sprint iteration assigned. If not, assign it now:

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

2. Create a feature branch. Name it after the ADO work item ID and a short slug:

   feature/<AB-id>-brief-description

   Examples:

   feature/AB47-recurring-event-support
   feature/AB52-apple-sign-in-web
   bugfix/AB61-calendar-rrule-parse-error

   In VS Code:

   Ctrl+Shift+P → Git: Create Branch

   Or via terminal:

   git checkout -b feature/AB47-recurring-event-support

3. Begin development. Commit frequently with descriptive messages that include the AB#<id> link:

   feat(calendar): add iCalendar RRULE parser AB#47
   feat(calendar): wire recurring events to API endpoint AB#47
   test(calendar): add unit tests for RRULE edge cases AB#47

---

Commit message format

Every commit touching a work item must include AB#<id>. ADO creates a link automatically.

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

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

feat(auth): add Apple Sign In to login screen AB#52
fix(calendar): correct timezone offset for recurring events AB#47
docs(adr): record auth provider decision — Clerk AB#18
chore(deps): upgrade @clerk/clerk-react to 5.x AB#71
refactor(api): extract event recurrence service into own module AB#47
test(marketplace): add listing validation unit tests AB#88

---

Creating a pull request

When your branch is ready for review:

1. Push the branch:

   git push -u origin feature/AB47-recurring-event-support

2. Create the PR using the GitHub Pull Requests extension:

   Ctrl+Shift+P → GitHub Pull Requests: Create Pull Request

   Or via the gh CLI:

   gh pr create `
     --title "feat(calendar): add recurring event support AB#47" `
     --body "Implements iCalendar RRULE parsing and recurring event creation via the API. AB#47" `
     --base main

3. PR description must include AB#<id> so ADO creates the linked artifact.

4. The existing .github/pull_request_template.md in this repo pre-fills a checklist. Fill in the summary and verify the AB# link is present.

---

Reviewing a PR in VS Code

1. Open the GitHub Pull Requests panel:

   Ctrl+Shift+P → GitHub Pull Requests: Focus on Pull Requests View

2. Select the PR to review. Click Checkout to check out the branch locally.

3. Use inline comments in the editor (right-click on a line → Add Comment) to leave feedback.

4. When ready, approve or request changes from the PR panel.

5. After merge, delete the branch:

   git branch -d feature/AB47-recurring-event-support
   git push origin --delete feature/AB47-recurring-event-support

---

Closing the work item

After the PR merges:

1. Update the ADO work item state to Resolved or Closed:

   az boards work-item update --id 47 --state Closed

2. If the item had a linked GitHub Issue, the sync automation updates the issue label to resolved and closes it automatically once the ADO item reaches Closed state.

3. Verify all Acceptance Criteria are met before setting Closed — this is a platform standards requirement.

---

Working with ADO from the terminal

The az boards commands below cover the most common daily operations. All assume the session defaults are set (az devops configure --defaults ...).

View a work item

az boards work-item show --id 47

Update state

az boards work-item update --id 47 --state Active
az boards work-item update --id 47 --state Resolved
az boards work-item update --id 47 --state Closed

Add a comment (discussion)

az boards work-item update --id 47 --discussion "Blocked on ADR for auth provider — resuming after Phase 0 closes."

Query your 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' ORDER BY [System.State]"

Query items in a specific area

az boards query --wiql "SELECT [System.Id],[System.Title],[System.State] FROM WorkItems WHERE [System.AreaPath] UNDER 'Heritage Community Hub\Platform' ORDER BY [System.Priority]"

Create a Task under a User Story

az boards work-item create `
  --type Task `
  --title "Write RRULE unit tests for monthly recurrence edge cases" `
  --parent 47 `
  --area "Heritage Community Hub\Platform" `
  --iteration "Heritage Community Hub\2026-Q3-S1" `
  --assigned-to "kris@hybridsolutions.cloud"

---

Monitoring GitHub Actions

The GitHub Actions extension shows CI status directly in VS Code.

1. Open the Activity Bar — click the GitHub Actions icon.
2. Expand the workflow run to see job-level status.
3. Click a failed step to view the log.

Alternatively, watch runs from the terminal:

# List recent workflow runs
gh run list --repo Heritage-Virginia/heritage-community-hub --limit 10

# Watch a specific run in real time
gh run watch <run-id> --repo Heritage-Virginia/heritage-community-hub

---

VS Code settings

Add to .vscode/settings.json to align the editor with HCS platform standards:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "git.autofetch": true,
  "git.confirmSync": false,
  "githubPullRequests.defaultMergeMethod": "squash",
  "githubPullRequests.pullBranch": "never",
  "todohighlight.isEnable": true,
  "todohighlight.keywords": [
    { "text": "TODO:",  "color": "#ff6b6b", "backgroundColor": "transparent" },
    { "text": "FIXME:", "color": "#feca57", "backgroundColor": "transparent" }
  ]
}

---

Daily workflow checklists

Starting your day

• [ ] az login (if your Azure session has expired)
• [ ] . D:\git\platform\scripts\Load-HCSEnvironment.ps1
• [ ] Check ADO board for Active items assigned to you
• [ ] Pull latest from main: git pull origin main
• [ ] Confirm your feature branch is up to date

During development

• [ ] Commits reference AB#<id> in every message
• [ ] Branch name includes the AB-<id> prefix
• [ ] ESLint and Prettier pass before committing
• [ ] TypeScript type-check passes: npm run build (no deploy)

Ending your day

• [ ] Push your branch: git push
• [ ] Add a comment to the ADO work item with status or blockers
• [ ] If a feature is complete and tests pass, open a PR
• [ ] Update the ADO item state (Active → Resolved if done)

Sprint review

• [ ] Verify all Closed items have all Acceptance Criteria met
• [ ] Move incomplete items to next sprint via ADO, with a comment explaining why
• [ ] Confirm linked GitHub Issues have been updated by the sync automation
• [ ] Review the phase gate — if all phase items are Closed, flag for phase advancement