AI project management agent rules for Windsurf

.windsurfrules

# Project Policy

This policy provides a single, authoritative, and machine-readable source of truth for AI coding agents and humans, ensuring that all work is governed by clear, unambiguous rules and workflows. It aims to eliminate ambiguity, reduce supervision needs, and facilitate automation while maintaining accountability and compliance with best practices.

# 1. Introduction

> Rationale: Sets the context, actors, and compliance requirements for the policy, ensuring all participants understand their roles and responsibilities.

## 1.1 Actors

> Rationale: Defines who is involved in the process and what their roles are.

- **User**: The individual responsible for defining requirements, prioritising work, approving changes, and ultimately accountable for all code modifications.
- **AI_Agent**: The delegate responsible for executing the User's instructions precisely as defined by PBIs and tasks.

## 1.2 Architectural Compliance

> Rationale: Ensures all work aligns with architectural standards and references, promoting consistency and quality across the project.

- **Policy Reference**: This document adheres to the AI Coding Agent Policy Document.
- **Includes**:
  - All tasks must be explicitly defined and agreed upon before implementation.
  - All code changes must be associated with a specific task.
  - All PBIs must be aligned with the PRD when applicable.

# 2. Fundamental Principles

> Rationale: Establishes the foundational rules that govern all work, preventing scope creep, enforcing accountability, and ensuring the integrity of the development process.

## 2.1 Core Principles

> Rationale: Lists the essential guiding principles for all work, such as task-driven development, user authority, and prohibition of unapproved changes.

1. Task-Driven Development: No code shall be changed in the codebase unless there is an agreed-upon task explicitly authorising that change.
2. PBI Association: No task shall be created unless it is directly associated with an agreed-upon Product Backlog Item (PBI).
3. PRD Alignment: If a Product Requirements Document (PRD) is linked to the product backlog, PBI features must be sense-checked to ensure they align with the PRD's scope.
4. User Authority: The User is the sole decider for the scope and design of ALL work.
5. User Responsibility: Responsibility for all code changes remains with the User, regardless of whether the AI Agent performed the implementation.
6. Prohibition of Unapproved Changes: Any changes outside the explicit scope of an agreed task are EXPRESSLY PROHIBITED.
7. Task Status Synchronisation: The status of tasks in the tasks index (1-tasks.md) must always match the status in the individual task file. When a task's status changes, both locations must be updated immediately.

## 2.2 PRD Alignment Check

All PBIs must be checked for alignment with the PRD. Any discrepancies must be raised with the User.

## 2.3 Integrity and Sense Checking

All data must be sense-checked for consistency and accuracy.

## 2.4 Scope Limitations

> Rationale: Prevents unnecessary work and keeps all efforts focused on agreed tasks, avoiding gold plating and scope creep.

- No gold plating or scope creep is allowed.
- All work must be scoped to the specific task at hand.
- Any identified improvements or optimizations must be proposed as separate tasks.

## 2.5 Change Management Rules

> Rationale: Defines how changes are managed, requiring explicit association with tasks and strict adherence to scope.

- Conversation about any code change must start by ascertaining the linked PBI or Task before proceeding.
- All changes must be associated with a specific task.
- No changes should be made outside the scope of the current task.
- Any scope creep must be identified, rolled back, and addressed in a new task.
- If the User asks to make a change without referring to a task, then the AI Agent must not do the work and must have a conversation about it to determine if it should be associated with an existing task or if a new PBI + task should be created.

# 3. Product Backlog Item (PBI) Management

> Rationale: Defines how PBIs are managed, ensuring clarity, traceability, and effective prioritisation of all work.

## 3.1 Overview

This section defines rules for Product Backlog Items (PBIs), ensuring clarity, consistency, and effective management throughout the project lifecycle.

## 3.2 Backlog Document Rules

> Rationale: Specifies how the backlog is documented and structured, so that all PBIs are tracked and managed in a consistent way.

- **Location Pattern**: docs/delivery/backlog.md
- **Scope Purpose Description**: The backlog document contains all PBIs for the project, ordered by priority.
- **Structure**:
  > Rationale: Defines the required table format for PBIs, ensuring standardisation and ease of use.
  - **Table**: `| ID | Actor | User Story | Status | Conditions of Satisfaction (CoS) |`

## 3.3 Principles
1. The backlog is the single source of truth for all PBIs.
2. PBIs must be ordered by priority (highest at the top).

## 3.4 PBI Workflow

> Rationale: Describes the allowed status values and transitions for PBIs, ensuring a controlled and auditable workflow.

### 3.4.1 Status Definitions
- **status(Proposed)**: PBI has been suggested but not yet approved.
- **status(Agreed)**: PBI has been approved and is ready for implementation.
- **status(InProgress)**: PBI is being actively worked on.
- **status(InReview)**: PBI implementation is complete and awaiting review.
- **status(Done)**: PBI has been completed and accepted.
- **status(Rejected)**: PBI has been rejected and requires rework or deprioritization.

### 3.4.2 Event Transitions
- **event_transition on "create_pbi": set to **Proposed**:
  1. Define clear user story and acceptance criteria.
  2. Ensure PBI has a unique ID and clear title.
  3. Log creation in PBI history.

- **event_transition on "propose_for_backlog" from Proposed to Agreed**:
  1. Verify PBI aligns with PRD and project goals.
  2. Ensure all required information is complete.
  3. Log approval in PBI history.
  4. Notify stakeholders of new approved PBI.

- **event_transition on "start_implementation" from Agreed to InProgress**:
  1. Verify no other PBIs are InProgress for the same component.
  2. Create tasks for implementing the PBI.
  3. Assign initial tasks to team members.
  4. Log start of implementation in PBI history.

- **event_transition on "submit_for_review" from InProgress to InReview**:
  1. Verify all tasks for the PBI are complete.
  2. Ensure all acceptance criteria are met.
  3. Update documentation as needed.
  4. Notify reviewers that PBI is ready for review.
  5. Log submission for review in PBI history.

- **event_transition on "approve" from InReview to Done**:
  1. Verify all acceptance criteria are met.
  2. Ensure all tests pass.
  3. Update PBI status and completion date.
  4. Archive related tasks and documentation.
  5. Log approval and completion in PBI history.
  6. Notify stakeholders of PBI completion.

- **event_transition on "reject" from InReview to Rejected**:
  1. Document reasons for rejection.
  2. Identify required changes or rework.
  3. Update PBI with review feedback.
  4. Log rejection in PBI history.
  5. Notify team of required changes.

- **event_transition on "reopen" from Rejected to InProgress**:
  1. Address all feedback from rejection.
  2. Update PBI with changes made.
  3. Log reopening in PBI history.
  4. Notify team that work has resumed.

- **event_transition on "deprioritize" from (Agreed, InProgress) to Proposed**:
  1. Document reason for deprioritization.
  2. Pause any in-progress work on the PBI.
  3. Update PBI status and priority.
  4. Log deprioritization in PBI history.
  5. Notify stakeholders of the change in priority.

### 3.4.3 Note

All status transitions must be logged in the PBI's history with timestamp and user who initiated the transition.

## 3.5 PBI History Log

> Rationale: Specifies how all changes to PBIs are recorded, providing a complete audit trail.

- **Location Description**: PBI change history is maintained in the backlog.md file.
- **Fields**:
  - **history_field(Timestamp)**: Date and time of the change (YYYYMMDD-HHMMSS).
  - **history_field(PBI_ID)**: ID of the PBI that was changed.
  - **history_field(Event_Type)**: Type of event that occurred.
  - **history_field(Details)**: Description of the change.
  - **history_field(User)**: User who made the change.

## 3.6 PBI Detail Documents

> Rationale: Provides a dedicated space for detailed requirements, technical design, and UX considerations for each PBI, ensuring comprehensive documentation and alignment across the team.

- **Location Pattern**: `docs/delivery/pbis/<PBI-ID>.md`
- **Purpose**: 
  - Serve as a mini-PRD for the PBI
  - Document the problem space and solution approach
  - Provide technical and UX details beyond what's in the backlog
  - Maintain a single source of truth for all PBI-related information
- **Required Sections**:
  - `# PBI-<ID>: <Title>`
  - `## Overview`
  - `## Problem Statement`
  - `## User Stories`
  - `## Technical Approach`
  - `## UX/UI Considerations`
  - `## Acceptance Criteria`
  - `## Dependencies`
  - `## Open Questions`
  - `## Related Tasks`
- **Linking**:
  - Must link back to the main backlog entry: `[View in Backlog](../backlog.md#user-content-<PBI-ID>)`
  - The backlog entry must link to this document: `[View Details](./pbis/<PBI-ID>.md)`
- **Ownership**:
  - Created when a PBI moves from "Proposed" to "Agreed"
  - Maintained by the team member implementing the PBI
  - Reviewed during PBI review process
  - 
# 4. Task Management

> Rationale: Defines how tasks are documented, executed, and tracked, ensuring that all work is broken down into manageable, auditable units.

## 4.1 Task Documentation

> Rationale: Specifies the structure and content required for task documentation, supporting transparency and reproducibility.

- **Location Pattern**: tasks/
- **File Naming**: <PBI-ID>-<TASK-ID>.md
- **Required Sections**:
  > Rationale: Required sections ensure all tasks are fully described and verifiable
  - `# [Task-ID] [Task-Name]`
  - `## Description`
  - `## Status History`
  - `## Requirements`
  - `## Implementation Plan`
  - `## Verification`
  - `## Files Modified`

## 4.2 Principles
1. Each task must have its own dedicated markdown file.
2. Task files must follow the specified naming convention.
3. All required sections must be present and properly filled out.
4. When adding a task to the tasks index, its markdown file MUST be created immediately and linked using the pattern `[description](./<PBI-ID>-<TASK-ID>.md)`.
5. Individual task files must link back to the tasks index using the pattern `[Back to task list](../<tasks-index-file>.md)`.

## 4.3 Task Workflow

> Rationale: Describes the allowed status values and transitions for tasks, ensuring a controlled and auditable workflow.

## 4.4 Task Status Synchronisation

To maintain consistency across the codebase:

1. **Immediate Updates**: When a task's status changes, update both the task file and the tasks index (1-tasks.md) in the same commit.
2. **Status History**: Always add an entry to the task's status history when changing status.
3. **Status Verification**: Before starting work on a task, verify its status in both locations.
4. **Status Mismatch**: If a status mismatch is found, immediately update both locations to the most recent status.

Example of a status update in a task file:
```
| 2025-05-19 15:02:00 | Created       | N/A      | Proposed  | Task file created | Julian |
| 2025-05-19 16:15:00 | Status Update | Proposed | InProgress | Started work      | Julian |
```

Example of the corresponding update in 1-tasks.md:
```
| 1-7 | [Add pino logging...](./1-7.md) | InProgress | Pino logs connection... |
```

## 4.5 Status Definitions
- **task_status(Proposed)**: The initial state of a newly defined task.
- **task_status(Agreed)**: The User has approved the task description and its place in the priority list.
- **task_status(InProgress)**: The AI Agent is actively working on this task.
- **task_status(Review)**: The AI Agent has completed the work and it awaits User validation.
- **task_status(Done)**: The User has reviewed and approved the task's implementation.
- **task_status(Blocked)**: The task cannot proceed due to an external dependency or issue.

## 4.6 Event Transitions
- **event_transition on "user_approves" from Proposed to Agreed**:
  1. Verify task description is clear and complete.
  2. Ensure task is properly prioritized in the backlog.
  3. Create task documentation file following the \_template.md pattern and link it in the tasks index.
   - The file must be named `<PBI-ID>-<TASK-ID>.md`
   - The task description in the index must link to this file
   - Analysis and design work must be undertaken and documented in the required sections of task file    
  4. Log status change in task history.

- **event_transition on "start_work" from Agreed to InProgress**:
  1. Verify no other tasks are InProgress for the same PBI.
  2. Create a new branch for the task if using version control.
  3. Log start time and assignee in task history.
  4. Update task documentation with implementation start details.

- **event_transition on "submit_for_review" from InProgress to Review**:
  1. Ensure all task requirements are met.
  2. Run all relevant tests and ensure they pass.
  3. Update task documentation with implementation details.
  4. Create a pull request or mark as ready for review.
  5. Notify the User that review is needed.
  6. Log submission for review in task history.

- **event_transition on "approve" from Review to Done**:
  1. Verify all acceptance criteria are met.
  2. Merge changes to the main branch if applicable.
  3. Update task documentation with completion details.
  4. Update task status and log completion time.
  5. Archive task documentation as needed.
  6. Notify relevant stakeholders of completion.
  7. Log approval in task history.

- **event_transition on "reject" from Review to InProgress**:
  1. Document the reason for rejection in task history.
  2. Update task documentation with review feedback.
  3. Notify the AI Agent of required changes.
  4. Update task status and log the rejection.
  5. Create new tasks if additional work is identified.

- **event_transition on "mark_blocked" from InProgress to Blocked**:
  1. Document the reason for blocking in task history.
  2. Identify any dependencies or issues causing the block.
  3. Update task documentation with blocking details.
  4. Notify relevant stakeholders of the block.
  5. Consider creating new tasks to address blockers if needed.

- **event_transition on "unblock" from Blocked to InProgress**:
  1. Document the resolution of the blocking issue in task history.
  2. Update task documentation with resolution details.
  3. Resume work on the task.
  4. Notify relevant stakeholders that work has resumed.

## 4.7 One In Progress Task Limit

Only one task per PBI should be 'InProgress' at any given time to maintain focus and clarity. In special cases, the User may approve additional concurrent tasks.

## 4.8 Task History Log

> Rationale: Specifies how all changes to tasks are recorded, providing a complete audit trail.

- **Location Description**: Task change history is maintained in the task's markdown file under the 'Status History' section.
- **Required Fields**:
  > Rationale: Defines the required fields for logging task history, ensuring all relevant information is captured.
  - **history_field(Timestamp)**: Date and time of the change (YYYY-MM-DD HH:MM:SS).
  - **history_field(Event_Type)**: Type of event that occurred.
  - **history_field(From_Status)**: Previous status of the task.
  - **history_field(To_Status)**: New status of the task.
  - **history_field(Details)**: Description of the change or action taken.
  - **history_field(User)**: User who initiated the change.

### 4.8.1 Format Example

```
| Timestamp | Event Type | From Status | To Status | Details | User |
|-----------|------------|-------------|-----------|---------|------|
| 2025-05-16 15:30:00 | Status Change | Proposed | Agreed | Task approved by Product Owner | johndoe |
| 2025-05-16 16:45:00 | Status Change | Agreed | InProgress | Started implementation | ai-agent-1 |
```

### 4.8.2 Task Validation Rules

> Rationale: Ensures all tasks adhere to required standards and workflows.

1. **Core Rules**:
   - All tasks must be associated with an existing PBI
   - Task IDs must be unique within their parent PBI
   - Tasks must follow the defined workflow states and transitions
   - All required documentation must be completed before marking a task as 'Done'
   - Task history must be maintained for all status changes
   - Only one task per PBI may be 'InProgress' at any time, unless explicitly approved
   - Every task in the tasks index MUST have a corresponding markdown file
   - Task descriptions in the index MUST be linked to their markdown files

2. **Pre-Implementation Checks**:
   - Verify the task exists and is in the correct status before starting work
   - Document the task ID in all related changes
   - List all files that will be modified
   - Get explicit approval before proceeding with implementation

3. **Error Prevention**:
   - If unable to access required files, stop and report the issue
   - For protected files, provide changes in a format that can be manually applied
   - Verify task status in both task file and index before starting work
   - Document all status checks in the task history

4. **Change Management**:
   - Reference the task ID in all commit messages
   - Update task status according to workflow
   - Ensure all changes are properly linked to the task
   - Document any deviations from the planned implementation

### 4.9 Version Control for Task Completion

> Rationale: Ensures consistent version control practices when completing tasks, maintaining traceability and automation.

1. **Commit Message Format**:
   - When a task moves from `Review` to `Done`, create a commit with the message:
     ```
     <task_id> <task_description>
     ```
   - Example: `1-7 Add pino logging to help debug database connection issues`

2. **Pull Request**:
   - Title: `[<task_id>] <task_description>`
   - Include a link to the task in the description
   - Ensure all task requirements are met before marking as `Done`

3. **Automation**:
   - When a task is marked as `Done`, run:
     ```bash
     git acp "<task_id> <task_description>"
     ```
   - This command should:
     1. Stage all changes
     2. Create a commit with the specified message
     3. Push to the remote branch

4. **Verification**:
   - Ensure the commit appears in the task's history
   - Confirm the task status is updated in both the task file and index
   - Verify the commit message follows the required format