feat: add Sprint Playbook Template and Implementation Guidelines for AI agents

2025-09-14 08:01:43 +02:00
parent addeb312b8
commit 941ad70567
3 changed files with 651 additions and 0 deletions
--- a/docs/framework/sprint-implementation-guidelines.md
+++ b/docs/framework/sprint-implementation-guidelines.md
@@ -0,0 +1,348 @@
+# 📘 Sprint Implementation Guidelines
+
+These guidelines define how the AI agent must implement a Sprint based on the approved **Sprint Playbook**.
+They ensure consistent execution, traceability, and alignment with user expectations.
+
+---
+
+## 0. Key Definitions
+
+**Logical Unit of Work (LUW)**: A single, cohesive code change that:
+- Implements one specific functionality 
+- Can be described in 1-2 sentences
+- Passes all relevant tests
+- Can be committed independently
+
+**Blocked Status (`🚫 blocked`)**: A user story cannot proceed due to:
+- Missing external dependencies 
+- Conflicting requirements
+- Failed tests that cannot be auto-fixed
+- Missing user clarification
+
+**AI-Responsible DoD Items**: Checkboxes the AI can verify and tick:
+- Code compiles and passes tests
+- Code committed and pushed to branch
+- Documentation updated
+- Sprint status updated to done
+
+**User-Only DoD Items**: Checkboxes only the user can tick:
+- Branch merged into main
+- Production deployment completed
+- External integrations verified
+
+---
+
+## 1. Git & Version Control Rules
+
+### 1.1 Commit Granularity
+
+* Commit after each **logical unit of work (LUW)**.
+* A user story may span multiple commits.
+* Do not mix unrelated changes (e.g., no “feature + formatting” in one commit).
+* Include tests for the LUW in the same commit if the story's DoD requires tests.
+* Local WIP commits may be squashed before delivery, but history must remain clear.
+
+### 1.2 Commit Message Style
+
+* Use **Conventional Commits** format:
+
+  ```
+  <type>(<scope>): <subject>
+
+  <body>
+
+  Refs: <Story-ID(s)>
+  ```
+* Example:
+
+  ```
+  feat(auth): add JWT middleware
+
+  Introduces HS256 verification for protected routes.
+  Returns 401 for missing/invalid/expired tokens.
+
+  Refs: US-3
+  ```
+* Allowed `<type>`: `feat`, `fix`, `refactor`, `perf`, `test`, `docs`, `build`, `ci`, `style`, `chore`, `revert`.
+
+### 1.3 Branching Strategy
+
+* Use **one dedicated branch per Sprint**:
+
+  * Naming: `feature/sprint-<id>-<short-goal>`
+  * Example: `feature/sprint-07-auth`
+* Branch created from `main` and kept up to date via rebase or merge.
+* `main` remains protected.
+
+**Sprint ID source of truth:** The Sprint ID **must** follow the “Sprint ID selection rule” in the How-to guide.  
+If no prior Playbooks exist in `docs/sprints/`, start at `01`; otherwise increment the greatest existing two-digit ID (keep zero-padding).
+
+### 1.4 Commit & Push Policy
+
+* Run build and fix issues before committing.
+* Commit and push regularly (at least daily).
+
+### 1.5 PR / Merge Rules
+
+* The AI agent **must not merge or open PRs**.
+* The AI’s responsibility ends with:
+  * Implementing all user stories.
+  * Committing changes to the Sprint branch.
+  * Ensuring the branch passes all tests.
+* The **user merges** the Sprint branch into `main`.
+
+---
+
+## 2. Playbook Status Updating
+
+### 2.1 User Stories
+* Update each story’s `Status` field (`🔲 todo` → `🚧 in progress` → `✅ done`).
+* Mark `✅ done` only when the story’s **DoD** is fully satisfied.
+
+### 2.2 Sprint Status (Top-Level)
+
+* Keep the top-level Sprint status current:
+
+  ```
+  Status: [🔲 not started | 🚧 in progress | 🛠️ implementing <user story id> | ✅ done]
+  ```
+
+### 2.3 Commit & Status Sync
+
+**Strict choreography**
+
+- **First commit of a story**  
+  Include the first code changes for `US-#` **and** update the Playbook in the same commit:
+  - Sprint status → `🛠️ implementing US-#`
+  - Story `US-#` status → `🚧 in progress`
+
+- **Final commit of a story**  
+  Include the completing code changes for `US-#` **and** update the Playbook in the same commit:
+  - Story `US-#` status → `✅ done`
+  - Tick any **AI-responsible** DoD items that became true in this commit (see below)
+
+- **DoD checkbox updates**  
+  Tick AI-responsible DoD items **in the same commit** that makes them true:
+  - ✅ Code compiles and passes automated tests
+  - ✅ Code is committed and pushed on branch  
+  - ✅ Documentation is updated
+  - ✅ Sprint status updated to done
+  
+  **NEVER tick user-only DoD items** such as:
+  - ❌ Branch is merged into main
+  - ❌ Production deployment completed
+  - ❌ External systems integration verified
+  
+- **No status-only commits**  
+  Avoid standalone “status update” commits. If a previous commit forgot a status/DoD tick, include it in the **very next** code commit for that story.
+
+
+### 2.4 Location & Traceability
+
+* Store Playbook in repo under `docs/sprints/sprint-<id>.md`.
+* Reference Story IDs in commit messages.
+
+### 2.5 End-of-Sprint Update
+
+* Update Sprint status → `✅ done`.
+* Update Playbook with final status changes.
+* Stop execution.
+
+---
+
+## 3. Coding & Testing Standards
+
+### 3.1 Style Guides
+
+* Follow project’s existing style guides.
+* Follow existing style guides exactly unless deviation prevents story completion.
+* If deviation is necessary, document rationale in commit body and ask user for approval.
+* Do not mix stylistic mass-changes with functional code.
+
+### 3.2 Code Quality
+
+* Keep changes minimal and scoped.
+* Favor readability and idiomatic solutions.
+* Maintain module boundaries.
+* Add/update docstrings and project docs when behavior changes.
+
+### 3.3 Testing Policy
+
+* **Unit tests**: required for all backend logic, utilities, data processing, and business logic.
+* **UI tests**: required only if the story's DoD explicitly mentions testing UI behavior.
+* Pure styling changes (CSS-only) do not require tests.
+* **Integration/E2E tests**: explicitly out of scope.
+* Maintain existing test coverage levels.
+
+### 3.4 Test Execution
+
+* Run relevant tests locally before committing.
+
+### 3.5 Prohibited
+
+* No large-scale refactors unless explicitly requested.
+* No new frameworks or test harnesses.
+* No speculative features.
+
+---
+
+## 4. Execution Flow
+
+### 4.1 Story Execution Workflow
+
+**STEP 1: Start Story**
+1. Verify previous story is `✅ done` (if `🚫 blocked`, STOP - do not proceed)
+2. Change story status from `🔲 todo` to `🚧 in progress`
+3. Change sprint status to `🛠️ implementing US-#`
+4. Commit these playbook changes with first code changes for the story
+
+**STEP 2: Implement Story (Loop)**
+For each LUW in the story:
+1. Write code for one logical unit of work
+2. Write tests if required by story DoD
+3. Run tests and fix any failures
+4. Commit LUW with conventional commit message including "Refs: US-#"
+5. Push commit to branch
+
+**STEP 3: Complete Story**
+1. Verify all story acceptance criteria are met
+2. Verify all AI-responsible DoD items are complete
+3. Run final test suite 
+4. Update story status to `✅ done`
+5. Tick completed AI-responsible DoD checkboxes 
+6. Commit these playbook updates
+7. Push final commit
+
+**STEP 4: Next Story or Block Handling**
+- If current story is `✅ done`: proceed to STEP 1 for next story
+- If current story is `🚫 blocked`: STOP execution, notify user, wait for instructions
+- If no more stories and all are `✅ done`: proceed to End-of-Sprint workflow
+
+### 4.2 Blocking Workflow
+
+**When ANY story becomes `🚫 blocked`:**
+1. Mark story status as `🚫 blocked` with specific reason
+2. Commit playbook changes immediately
+3. Notify user with blocker details
+4. **STOP all sprint work** - do not proceed to next stories
+5. Wait for user to provide resolution instructions
+6. Only resume when user gives explicit unblocking guidance
+
+**Critical Rule: NO STORY PROGRESSION DURING BLOCKING**
+- Do not start new stories while any story is `🚫 blocked`
+- Do not attempt workarounds or fixes without user approval
+- Sprint execution is completely paused until all blocks are resolved
+
+### 4.3 End-of-Sprint Workflow
+
+**STEP 1: Final Verification**
+1. Verify all stories are `✅ done` (if any are `🚫 blocked`, STOP and notify user)
+2. Run complete test suite
+3. Update any remaining documentation
+
+**STEP 2: Sprint Completion**  
+1. Update sprint status to `✅ done`
+2. Tick any remaining AI-responsible DoD items
+3. Commit final changes
+4. Push branch to remote
+
+**STEP 3: Stop Execution**
+- Report sprint completion to user
+- Do not merge branch or open PRs
+
+---
+
+## 5. Documentation & Communication
+
+### 5.1 Inline Comments
+
+* Update/add comments for new or changed functions/classes/modules.
+* Keep concise and technical.
+
+### 5.2 Project Docs
+
+* Update README/API docs/configs when public-facing behavior changes.
+* Docs updated in **same commit** as related code.
+
+### 5.3 Exclusions
+
+* No separate Sprint summary reports.
+* No speculative documentation outside scope.
+
+---
+
+## 6. Failure & Error Handling
+
+### 6.1 Error Response Protocol
+
+**MANDATORY STEPS when encountering any blocker:**
+1. Stop current work immediately
+2. Mark story status as `🚫 blocked` in playbook
+3. Add specific blocker reason to playbook
+4. Commit playbook changes
+5. Ask user for explicit resolution 
+6. Wait for user response - do not proceed
+
+### 6.2 Specific Error Actions
+
+**Test Failures:**
+1. Run tests again to confirm failure
+2. Copy exact error messages
+3. Mark story as `🚫 blocked` with reason: "Tests failing: [error summary]"
+4. Ask user: "Tests are failing with error: [exact error]. Should I fix this or wait for guidance?"
+
+**Missing Dependencies:**
+1. Identify exactly what is missing
+2. Mark story as `🚫 blocked` with reason: "Missing dependency: [name]"
+3. Ask user: "Missing dependency [name]. Should I install it or mock it for testing?"
+
+**Conflicting Requirements:**
+1. Document the specific conflict
+2. Mark story as `🚫 blocked` with reason: "Conflicting requirements: [details]"  
+3. Ask user: "Found conflicting requirements: [details]. Which approach should I follow?"
+
+**Build/Compilation Failures:**
+1. Copy exact build error
+2. Mark story as `🚫 blocked` with reason: "Build failing: [error summary]"
+3. Ask user: "Build is failing with: [exact error]. How should I resolve this?"
+
+### 6.3 Prohibited Actions During Blocking
+
+**NEVER do these when `🚫 blocked`:**
+- Continue to next story
+- Make speculative fixes
+- Change requirements to work around issues
+- Skip failing tests
+- Implement workarounds without approval
+
+### 6.4 Unblocking Requirements
+
+**AI can only resume work after user provides:**
+- Explicit instruction on how to resolve the blocker
+- Modified requirements if applicable  
+- Confirmation that workaround approach is acceptable
+
+---
+
+## 7. Sprint Wrap-Up
+
+### 7.1 Completion Criteria
+
+Sprint is complete when:
+
+* All user stories = `✅ done`.
+* Sprint status = `✅ done`.
+* Final status updates completed.
+* Code committed to Sprint branch.
+* Docs and comments updated.
+* Tests passing (when applicable).
+
+### 7.2 Handover
+
+* AI stops execution.
+* Sprint branch remains unmerged.
+
+### 7.3 Final Note
+
+* No changes beyond Sprint scope.
+* Playbook + Git history act as audit record.