update content for agile development

Shiran Rubin · Shiran Rubin · commit 25e03dcc2305 · 2025-09-18T16:40:40.000+01:00
diff --git a/docs/agile-development/README.md b/docs/agile-development/README.md
@@ -1,6 +1,6 @@
 # Agile Development
 
-In this documentation we refer to the team working on an engagement a **"Crew"**. This includes the dev team, dev lead, PM, data scientists, etc.
+In this documentation we refer to the cross-functional delivery team as a **"Crew"** (i.e., the team responsible for delivery on the engagement). This includes the dev team, dev lead, product manager (PM), data scientists, etc.
 
 ## Why Agile
 
@@ -13,16 +13,27 @@ In this documentation we refer to the team working on an engagement a **"Crew"**
 
 We care about the goal for each activity, but not necessarily about how they are accomplished. The suggestions in parenthesis are common ways to accomplish the goals.
 
-- We keep a shared backlog of work, that everyone in the team can always access (ex. Azure DevOps or GitHub)
+- We keep a shared backlog of work that everyone on the team can access (e.g., Azure DevOps, GitHub, Jira or other backlog tools)
 - We plan our work in iterations with clear goals (ex. sprints)
 - We have a clear idea of when work items are ready to implement (ex. definition of ready)
 - We have a clear idea of when work items are completed (ex. definition of done)
 - We communicate the progress in one place that everyone can access, and keep the progress up to date (ex. sprint board and daily standups)
 - We reflect on our work regularly to make improvements (ex. retrospectives)
-- The team has a clear idea of the roles and responsibilities in the project (ex. Dev lead, TPM, Process Lead etc.)
-- The team has a joint idea of how we work together (ex. team agreement)
+- The team has a clear idea of the roles and responsibilities in the project (e.g., dev lead, Technical Program Manager (TPM), Process Lead, etc.)
+- The team has a clear idea of how we work together (ex. team agreement)
 - We value and respect the opinions and work of all team members.
 
+## AI tooling considerations
+
+Teams are increasingly adapting traditional Scrum practices to take advantage of AI tools and workflows. The tools emphasize rapid iteration, short discovery/validation cycles, and AI-assisted asset generation. Consider these principles as you tailor your process:
+
+- Favor frequent, lightweight planning and validation over rigid, fixed-length cadences when it helps accelerate feedback loops and reduce cycle time.
+- Use AI-assisted tooling (for example, GitHub Copilot or planning assistants) to accelerate planning, generate drafts for reviews, and improve productivity—while maintaining human oversight and review.
+- Embrace shorter spikes and early validation (especially for UX and data science work) to de-risk solutions earlier.
+- Consider pod models that embed business stakeholders into the delivery team when it helps reduce handoffs and increase decision speed.
+
+These are patterns, not prescriptions — adapt them to fit your engagement and stakeholder needs.
+
 ## References
 
 - [What Is Scrum?](https://www.scrum.org/resources/what-is-scrum)
diff --git a/docs/agile-development/advanced-topics/collaboration/pair-programming-tools.md b/docs/agile-development/advanced-topics/collaboration/pair-programming-tools.md
@@ -18,9 +18,9 @@ Additionally, scheduling these working sessions in advance ensures intentional c
 
 With its cloud-based infrastructure, GitHub Codespaces presents a highly efficient and simplified approach to real-time collaborative coding. As a result, new team members can easily access the GitHub project and begin coding within seconds, without requiring installation on their local machines. This seamless, integrated solution for pair programming offers a streamlined workflow, allowing you to direct your attention towards producing exemplary code, free from the distractions of cumbersome setup processes.
 
-### VSCode Live Share
+### Visual Studio Live Share
 
-[VSCode Live Share](https://code.visualstudio.com/learn/collaboration/live-share) is specifically designed for pair programming and enables you to work on the same codebase, in real-time, with your team members. The arduous process of configuring complex setups, grappling with confusing configurations, straining one's eyes to work on small screens, or physically switching keyboards is not a problem with LiveShare. This innovative solution enables seamless sharing of your development environment with your team members, facilitating smooth collaborative coding experiences.
+[Visual Studio Live Share](https://code.visualstudio.com/learn/collaboration/live-share) is specifically designed for pair programming and enables you to work on the same codebase, in real-time, with your team members. The arduous process of configuring complex setups, grappling with confusing configurations, straining one's eyes to work on small screens, or physically switching keyboards is not a problem with LiveShare. This solution enables seamless sharing of your development environment with your team members, facilitating smooth collaborative coding experiences.
 
 Fully integrated into Visual Studio Code and Visual Studio, LiveShare offers the added benefit of terminal sharing, debug session collaboration, and host machine control. When paired with GitHub Codespaces, it presents a potent tool set for effective pair programming.
 
diff --git a/docs/agile-development/advanced-topics/collaboration/teaming-up.md b/docs/agile-development/advanced-topics/collaboration/teaming-up.md
@@ -24,7 +24,7 @@ Some potential steps in this phase may be as following (not limited):
 
 - Identification of "Software Craftspersonship" areas which means the tools and methods will be widely used during the engagement and taking the required actions on team upskilling side if necessary.
 
-  - GitHub, VSCode LiveShare, AzDevOps, necessary development tools & libraries ... more.
+  - GitHub, Visual Studio Live Share, Azure DevOps, necessary development tools & libraries, and other collaboration tools.
   - If upskilling on certain topic(s) is needed, identifying the areas and arranging code spikes for increasing the team knowledge on the regarding topic(s).
 
 - Identification of communication channels, feedback loops and recurrent team call slots out of regular sprint meetings
diff --git a/docs/agile-development/async-collaboration-checklist.md b/docs/agile-development/async-collaboration-checklist.md
@@ -0,0 +1,29 @@
+# Asynchronous collaboration & accessibility checklist
+
+Purpose: Practical guidance for distributed teams to collaborate effectively and inclusively across time zones.
+
+## Async standup template
+- Summary (yesterday): short bullet(s)
+- Plan (today): short bullet(s)
+- Blockers / help needed: short bullet(s)
+
+Post the above in a shared channel or issue and use threaded replies for follow-ups.
+
+## Async demo guidance
+- Record a short demo (5-8 minutes) focusing on the outcome and acceptance criteria.
+- Include a short transcript or key bullet points in the PR or release note.
+- Add captions or a brief written summary for accessibility.
+
+## Accessibility checklist for artifacts
+- Provide alt text for images and diagrams.
+- Ensure headings and lists are semantically correct in markdown.
+- Provide captions/transcripts for videos and demos.
+- Ensure code samples are in accessible font sizes when shared in docs.
+
+## Meeting scheduling and fairness
+- Rotate meeting times or facilitators to share burden across time zones.
+- Use asynchronous agendas: post an agenda in advance and capture decisions in writing.
+
+## PR and review expectations
+- Include a short PR description and steps to validate.
+- Mark urgent reviews clearly; otherwise assume a 24-48 hour review window for non-urgent PRs.
diff --git a/docs/agile-development/backlog-management.md b/docs/agile-development/backlog-management.md
@@ -11,7 +11,7 @@
 
 - Consider the backlog refinement as an ongoing activity, that expands outside of the typical "Refinement meeting".
 - The team should decide on and have a clear understanding of a [definition of ready](./team-agreements/definition-of-ready.md) and a [definition of done](./team-agreements/definition-of-done.md).
-- The team should have a clear understanding of what constitutes good acceptance criteria for a story/task, and decide on how stories/tasks are handled. Eg. in some projects, stories are refined as a crew, but tasks are created by individual developers on an as needed bases.
+- The team should have a clear understanding of what constitutes good acceptance criteria for a story/task, and decide on how stories/tasks are handled. e.g., in some projects, stories are refined as a crew, but tasks are created by individual developers on an as-needed basis.
 - Technical debt is mostly due to shortcuts made in the implementation as well as the future maintenance cost as the natural result of continuous improvement. Shortcuts should generally be avoided. In some rare instances where they happen, prioritizing and planning improvement activities to reduce this debt at a later time is the recommended approach.
 
 ## Resources
diff --git a/docs/agile-development/branching-and-cicd.md b/docs/agile-development/branching-and-cicd.md
@@ -0,0 +1,81 @@
+# Branching & CI/CD Guidance
+
+Purpose: Provide a concise, practical policy and examples teams can adopt for integration, branching and CI gating. This page is intentionally short — teams should adapt the policy to their project and toolchain.
+
+## Recommended approach
+- Prefer trunk-based development where possible for new projects. Use short-lived feature branches when necessary and merge frequently into the default integration branch (commonly `main` or `trunk`).
+- Use branch protection rules on the integration branch to enforce quality gates (required passing CI, required code reviews, status checks).
+- Keep releases simple: use tags/releases from the integration branch and keep release process documented separately.
+
+## Example branch protection rules
+- Require at least one approving reviewer for pull requests.
+- Require successful CI pipeline status checks before merge.
+- Require up-to-date branch before merge if your policy prefers.
+
+## Sample minimal GitHub Actions CI gate (example)
+```yaml
+name: ci
+on: [pull_request]
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      - name: Install
+        run: npm ci
+      - name: Run tests
+        run: npm test
+```
+
+## Merge policy checklist (suggested)
+- [ ] Code compiles and automated tests pass in CI
+- [ ] At least one approving reviewer has reviewed the change
+- [ ] The change has an associated work item or issue
+- [ ] Documentation updated where applicable
+
+## Tips
+- Keep feature branches short-lived; frequent merges reduce integration risk.
+- Automate as much of the gate (linting, unit tests, basic security scans) as possible to keep manual review focused on design and architecture.
+- Adapt branch protection to match team size and delivery cadence.
+
+---
+
+## Alignment with CI/CD guidance
+This page complements the central CI/CD guidance in `docs/CI-CD/README.md`. Key expectations teams should follow:
+
+- The integration (main) branch should be continuously shippable and stable — at any point we should be able to deploy a build from `main` to production if needed.
+- Run a quality pipeline (linting, unit tests, basic integration tests) on each PR and on merges to the integration branch.
+- Provision cloud resources and environment configuration via infrastructure-as-code (for example Terraform, Bicep, Pulumi) and exercise them in non-production environments.
+- Deploy release candidates automatically to a non-production environment to validate integration and operational concerns.
+- Automate release and rollback procedures so releases are repeatable and auditable.
+
+## Tools (reference)
+Refer to `docs/CI-CD/README.md` for more detail on recommended tools. Common options include:
+- Azure Pipelines — recommended/used across many Microsoft engagements for CI/CD.
+- GitHub Actions, Jenkins, CircleCI, TravisCI — viable alternatives depending on project constraints.
+
+## AI-assisted CI/CD authoring
+AI tools can accelerate writing CI/CD pipeline YAML, jobs, and scripting snippets, but they must be used with explicit guardrails.
+
+Suggested workflow:
+- Use AI to draft CI/CD pipeline templates or job steps as a starting point (for example, generating a minimal GitHub Actions workflow).
+- Run the draft pipeline in a safe non-production environment or CI sandbox to validate syntax and basic behaviour.
+- Require a human reviewer to validate generated steps for correctness, idempotence, and security implications (especially around secrets, permissions, and external actions).
+- Add tests or smoke checks to the pipeline so changes can be validated automatically when the pipeline runs.
+- Promote approved templates into a central location (for example, `.github/workflows/` or a shared pipeline template repository) so teams reuse vetted, audited pipelines.
+
+Guardrails and checklist (before merging AI-generated pipeline changes):
+- [ ] Human review completed and documented in PR
+- [ ] No secrets or credentials are hard-coded
+- [ ] Required linting and syntax checks pass locally and in CI
+- [ ] Security and license scans run and report no critical issues
+- [ ] Pipeline steps are idempotent and have clear rollback strategies where applicable
+- [ ] Generated content is annotated in the PR description (e.g., "AI-assisted draft") so reviewers know to apply extra scrutiny
+
+Notes:
+- AI-generated pipelines are excellent for reducing boilerplate and accelerating iteration, but they do not replace domain knowledge and security review.
+- Maintain a small set of vetted pipeline templates to reduce risk and improve reproducibility.
diff --git a/docs/agile-development/ceremonies.md b/docs/agile-development/ceremonies.md
@@ -8,7 +8,9 @@
 - The Planning defines how the work is going to be completed in the sprint.
 - Stories fit in a sprint and are [designed](../design/design-reviews) and [ready](./team-agreements/definition-of-ready.md) before the planning.
 
-> **Note:** Self assignment by team members can give a feeling of fairness in how work is split in the team. Sometime, this ends up not being the case as it can give an advantage to the loudest or more experienced voices in the team. Individuals also tend to stay in their comfort zone, which might not be the right approach for their own growth.*
+> **Note:** Self assignment by team members can give a feeling of fairness in how work is split in the team. Sometimes, this ends up not being the case as it can give an advantage to the loudest or more experienced voices in the team. Individuals also tend to stay in their comfort zone, which might not be the right approach for their own growth.*
+
+> Working with AI tools note: Some teams adapt sprint planning cadence to support the faster patterns which AI tools bring — favoring short, lightweight planning events or a continuous planning cadence when this enables faster feedback and delivery. Use AI-assisted planning tools (e.g., Copilot or planning assistants) to draft plans or acceptance criteria, but always validate and adapt output collaboratively with the team.
 
 ### Sprint Goal
 
@@ -29,7 +31,7 @@ Example 1: Preparing in advance
 - The dev lead uses their experience (past and on the current project) and the estimation made for these stories to gauge how many should be in the sprint.
 - The dev lead asks the entire team to look at the tentative sprint backlog in advance of the sprint planning.
 - The dev lead assigns stories to specific developers after confirming with them that it makes sense
-- During the sprint planning meeting, the team reviews the sprint goal and the stories. Everyone confirm they understand the plan and feel it's reasonable.
+- During the sprint planning meeting, the team reviews the sprint goal and the stories. Everyone confirms they understand the plan and feel it's reasonable.
 
 Example 2: Building during the planning meeting
 
@@ -69,7 +71,7 @@ Examples of approaches for task creation and assignment:
 - The estimation process is improved over time and discussed on a regular basis.
 - Estimation is inclusive of the different individuals in the team.
 
-Rough estimation is usually done for a generic SE 2 dev.
+Rough estimation is usually done using a representative mid-level engineer (for example, a typical mid-level developer) or based on team historical velocity.
 
 ### Example 1: T-shirt Sizes
 
@@ -87,7 +89,7 @@ Rough estimation is usually done for a generic SE 2 dev.
 
 - The team does planning poker and estimates in story points
 - Story points are roughly used to estimate how much can be done in next sprint
-- The dev lead and the TPM uses the past sprints and observed velocity to adjust project end date forecasting
+- The dev lead and the Technical Program Manager (TPM) use past sprints and observed velocity to adjust project end date forecasting
 
 ### Other Considerations
 
diff --git a/docs/agile-development/roles.md b/docs/agile-development/roles.md
@@ -1,6 +1,7 @@
 # Agile/Scrum Roles
 
 - We prefer using "process lead" over "scrum master". It describes the same role.
+- Some teams use the term "Process Lead" while others use "Scrum Master". Both typically refer to the role responsible for facilitating team process, removing impediments, and supporting continuous improvement. Choose the name that best fits your team's context and clarify responsibilities on first use.
 
 This section has links directing you to definitions for the traditional roles within Agile/Scrum.  After reading through the best practices you should have a basic understanding of the key Agile roles in terms of what they are and the expectations for the role.
 
diff --git a/docs/agile-development/team-agreements/definition-of-done.md b/docs/agile-development/team-agreements/definition-of-done.md
@@ -15,7 +15,7 @@ The development team should decide together what their Definition of Done is and
 - [ ] Code review is complete
 - [ ] UX review is complete (if applicable)
 - [ ] Documentation is updated
-- [ ] The feature is merged into the develop branch
+- [ ] The feature is merged into the project's default integration branch (for example, `main` or `trunk`), or otherwise merged according to the project's agreed branching strategy.
 - [ ] The feature is signed off by the product owner
 
 ## Sprint Goal
@@ -24,7 +24,7 @@ The development team should decide together what their Definition of Done is and
 - [ ] Product backlog is updated
 - [ ] Functional and Integration tests pass
 - [ ] Performance tests pass
-- [ ] End 2 End tests pass
+- [ ] End-to-end tests pass
 - [ ] All bugs are fixed
 - [ ] The sprint is signed off from developers, software architects, project manager, product owner etc.
 
diff --git a/docs/agile-development/team-agreements/definition-of-ready.md b/docs/agile-development/team-agreements/definition-of-ready.md
@@ -6,7 +6,7 @@ When the development team picks a user story from the top of the backlog, the us
 
 ## What it is
 
-*Definition of Ready* is the agreement made by the scrum team around how complete a user story should be in order to be selected as candidate for estimation in the sprint planning. These can be codified as a checklist in user stories using [GitHub Issue Templates](https://help.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository) or [Azure DevOps Work Item Templates](https://learn.microsoft.com/en-us/azure/devops/boards/backlogs/work-item-template?view=azure-devops&tabs=browser).
+*Definition of Ready* is the agreement made by the scrum team around how complete a user story should be in order to be selected as candidate for estimation in the sprint planning. These can be codified as a checklist in user stories using [GitHub Issue Templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) or [Azure DevOps Work Item Templates](https://learn.microsoft.com/en-us/azure/devops/boards/backlogs/work-item-template?view=azure-devops&tabs=browser).
 
 It can be understood as a checklist that helps the Product Owner to ensure that the user story they wrote contains all the necessary details for the scrum team to understand the work to be done.
 
diff --git a/docs/agile-development/team-agreements/team-manifesto.md b/docs/agile-development/team-agreements/team-manifesto.md
