57dcebd640
Restructured the repository into a monorepo to better organize application code and maintenance scripts. ## Workspace Structure - web-app: Next.js application (all app code moved from root) - housekeeping: Database backup and maintenance scripts ## Key Changes - Moved all application code to web-app/ using git mv - Moved database scripts to housekeeping/ workspace - Updated Dockerfile for monorepo build process - Updated docker-compose files (volume paths: ./web-app/etc/hosts/) - Updated .gitignore for workspace-level node_modules - Updated documentation (README.md, CLAUDE.md, CHANGELOG.md) ## Migration Impact - Root package.json now manages workspaces - Build commands delegate to web-app workspace - All file history preserved via git mv - Docker build process updated for workspace structure 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
349 lines
10 KiB
Markdown
349 lines
10 KiB
Markdown
# 📘 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.
|