Add agile workflow document

agile-workflow.md

@@ -0,0 +1,199 @@
+# Our Agile Workflow
+
+## Table of Contents
+
+- [Why This Document](#why-this-document)
+- [How Work Arrives](#how-work-arrives)
+- [Async Ceremonies](#async-ceremonies)
+- [Sync Ceremonies](#sync-ceremonies)
+- [Workflow](#workflow)
+- [Technical Practices](#technical-practices)
+- [Checklists](#checklists)
+- [Future Considerations](#future-considerations)
+- [Glossary](#glossary)
+
+## Why This Document
+
+We're a new team. None of us have worked together using a structured development workflow before. This document describes a lightweight agile process tailored to our team: 4 senior/principal engineers and 1 engineering manager, working on strategic OpenShift initiatives.
+
+This is not textbook Scrum. It borrows what's useful and leaves out what isn't. The goal is to give us just enough structure to coordinate, stay visible to stakeholders, and improve over time, without drowning in meetings or process.
+
+We'll revisit this document regularly. If something doesn't work, we change it.
+
+## How Work Arrives
+
+Our team receives strategic initiatives (OCPSTRAT tickets) from upper management. These are high-level goals for an OpenShift release cycle. Our job is to:
+
+1. Understand the intent and success criteria of each initiative.
+2. Break them down into epics and stories in Jira.
+3. Deliver them within the release cycle.
+
+We won't necessarily tackle an entire OCPSTRAT initiative in one cycle. We scope what's realistic.
+
+## Async Ceremonies
+
+### Refinement
+
+Refinement means turning a vague initiative into work an engineer can pick up. A story is "refined" when any engineer on the team could read it and understand what to build and when it's done.
+
+**Process:**
+
+1. **PM Kickoff** (30-60 min, once per OCPSTRAT):
+   - PM explains the what/why, success criteria, and priority.
+   - The primary and secondary architect attend.
+   - Happens before iteration planning when new OCPSTRAT work enters the cycle.
+2. **Async Breakdown**: The primary and secondary architect break the OCPSTRAT into epics and stories in Jira.
+   - **Epic DoD:** A deliverable chunk of work.
+     - Goal
+     - Scope
+     - Mapping back to the OCPSTRAT
+     - Technical design (architecture decisions, component interactions, API contracts), done by the primary and secondary architects
+   - **Story DoD**: Small enough for one engineer to finish in a few days to an iteration.
+     - Summary
+     - Scope
+     - Acceptance criteria
+     - T-shirt size estimate (S/M/L). Anything bigger than L, split it.
+     - Technical design (only if non-obvious), added by whoever picks up the story
+3. **Open Questions**: Go to the optional weekly refinement slot (45 min).
+
+**Rules:**
+
+- Don't refine blocked work. Defer until it's unblocked.
+- Refinement is **ongoing**. See [Workflow](#workflow) for how refinement continues during the iteration.
+
+### Async Review
+
+Rest of team reviews refined stories in Jira, leaves comments.
+
+## Sync Ceremonies
+
+**Iteration Planning** (start of iteration, 20 min)
+
+- Each engineer picks refined stories from the backlog for the next 3 weeks.
+- Stories must be refined before they enter an iteration. If they're not, they go back to refinement.
+- Engineers volunteer to take unrefined stories for refinement in the upcoming iteration.
+
+**Weekly Sync** (Wednesdays, 30 min)
+
+- Quick round: what's progressing, what's blocked, any decisions needed.
+- The facilitator runs the [Jira sanity check](#facilitator-jira-sanity-check) for each engineer.
+
+**Optional Refinement Slot** (weekly, 45 min)
+
+- For open questions from async refinement that need face-to-face discussion.
+- The meeting is optional, not the attendance. If it happens, everyone joins.
+- PM is invited when their input is needed.
+- Cancelled by facilitator if there's nothing to discuss.
+
+**Iteration Review + Retrospective** (end of iteration, 60-75 min)
+
+- First half (30 min): each engineer briefly shows what they delivered.
+- 5 min break.
+- Second half (30 min): what went well, what didn't, one thing to change next iteration.
+
+**Rotation:** First facilitator picked at kick-off. After every 2 iterations, rotate to the next person.
+
+## Workflow
+
+We work in **3-week iterations**, aligned with the broader OpenShift release schedule. Each release cycle contains multiple iterations. Iterations give us a predictable rhythm for planning, delivering, and reflecting.
+
+**Kickoff:**
+
+- The team selects the primary and secondary architect for each OCPSTRAT.
+- The team selects the first facilitator.
+
+**Getting started on a new OCPSTRAT:**
+
+- The primary and secondary architect refine the epics and create unrefined stories.
+- Once at least one epic is refined with a set of stories, the rest of the team gets involved.
+
+**During the iteration:**
+
+- In iteration planning, each engineer picks a refined story to develop and a few unrefined stories to refine.
+- During the iteration, you develop your story (**in pairs**, optional but encouraged) and refine the others.
+- When you finish your story, let the team know in weekly sync, grab another refined story from the backlog and pull it into the current iteration.
+- When you finish refining your stories, grab the next one.
+- If a story turns out much larger than expected during development, break it down, re-estimate, and put the new stories in the backlog.
+
+## Technical Practices
+
+We follow engineering practices inspired by Extreme Programming (XP). Most are already part of how we work.
+
+- **Pair Programming**: Encouraged, especially for complex or unfamiliar work. Not mandatory for every task.
+- **Test-Driven Development (TDD)**: Optional, but recommended. Write tests before implementation when it makes sense.
+- **Continuous Integration**: All code goes through CI. Broken builds get fixed immediately.
+- **Small Releases**: Release often behind feature gates. Get code into the build early to allow time for soak and feedback before GA.
+- **Collective Code Ownership**: Anyone can modify any part of the codebase. No single owner bottlenecks.
+- **Code Reviews**: Every change gets reviewed before merge.
+- **Refactoring**: Improve code structure continuously. Leave the codebase better than you found it.
+- **Simple Design (YAGNI)**: Build what's needed now. Don't over-engineer for hypothetical future requirements.
+
+## Checklists
+
+### Development DoD
+
+A story is done when:
+
+- [ ] Code reviewed and approved
+- [ ] PR merged
+- [ ] CI passing
+- [ ] Unit tests fully cover new behaviour
+- [ ] e2e tests cover new behaviour (if applicable)
+- [ ] Manual tests on latest OCP cluster
+- [ ] Exploratory tests
+- [ ] Release notes updated (if applicable)
+- [ ] Documentation updated (if applicable)
+- [ ] Behind feature gate (if applicable)
+- [ ] Jira updated: PR added, status updated, linked issues updated (if applicable)
+
+### Engineer
+
+Things every engineer is responsible for, every iteration:
+
+- [ ] Keep assigned Jira tickets up to date: status, comments, and blockers.
+- [ ] Stories are refined before pulling them into an iteration.
+- [ ] Demo what you merged in the iteration review.
+
+### Architect Refinement
+
+- [ ] PM Kickoff scheduled before iteration planning
+- [ ] At least one refined epic with stories ready before first iteration planning
+
+### Facilitator Duties
+
+During rotation:
+
+- [ ] Set up sync ceremony meetings (planning, weekly sync, review + retro)
+- [ ] Inform team if the optional refinement slot happens, latest on the day of
+- [ ] Facilitate sync ceremonies: keep time and lead the agenda
+- [ ] Run the [Jira sanity check](#facilitator-jira-sanity-check) during the weekly sync
+
+### Facilitator Jira Sanity Check
+
+The facilitator checks for each engineer during the weekly sync:
+
+- [ ] Is the story assigned to the engineer working on it?
+- [ ] Is the status up to date?
+- [ ] PR linked to the story if there is one?
+- [ ] Status of stories in refinement up to date?
+- [ ] Questions/comments on stories in refinement answered?
+- [ ] Does the story have the correct parent epic?
+
+## Future Considerations
+
+Not relevant for our current release cycle, but things we've thought about.
+
+- **Multi-pod collaboration**: When an OCPSTRAT is shared across multiple pods, the lead architects from each pod align upfront to split epics among teams and sync bi-/tri-weekly.
+
+## Glossary
+
+- **OCPSTRAT**: A strategic initiative for OpenShift, assigned to one or more pods.
+- **Epic**: A large, deliverable chunk of work within an OCPSTRAT. Can span multiple iterations.
+- **Story**: A small unit of work within an epic. Should be completable by one engineer within one iteration.
+- **Iteration** (aka sprint): A 3-week development cycle.
+- **Refinement**: The process of turning vague requirements into well-defined, actionable stories.
+- **Acceptance criteria**: Conditions that must be met for a story to be considered done.
+- **T-shirt size**: A rough estimate of effort (S/M/L).
+- **Primary architect**: The lead engineer responsible for the technical direction of an OCPSTRAT.
+- **Secondary architect**: The primary architect's partner, helps with epic refinement and serves as stand-in.
+- **DoD**: Definition of Done.