knee-cola/evidencija-rezija
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
evidencija-rezija/web-app/docs/framework/sprint-implementation-guidelines.md
Knee Cola 57dcebd640 refactor: convert repository to monorepo with npm workspaces 
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>
2025-12-25 12:13:04 +01:00

10 KiB
Raw Permalink Blame History

📘 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.
Reference in New Issue View Git Blame Copy Permalink