vibecoding — Windsurf Rules

This file documents project-specific rules, exceptions, and implementation details for this repository. For organization-wide standards, see global_rules.md.

• All project tasks must be recorded in tasks.md using a clear, unique identifier (e.g., TASK-001). The Windsurf AI IDE should provide tools for easy creation and management of these tasks. • Each task entry must include: • Task ID and a concise, descriptive title. • Detailed description of the task. • Assignee: The person or team responsible (e.g., @username or "AI Cascade"). • Status: One of [Open, In Progress, Blocked, Complete], with a status icon placed in the same cell as the status (e.g., 🟢 Open, ✅ Complete). • Status Icons: • 🟢 Open • 🟡 In Progress • 🔴 Blocked • ✅ Complete • Link(s) to related user stories (e.g., in docs/user_stories.md), implementation files, and test files. The IDE should facilitate creating these links. • Date created and last updated (use ISO 8601 format: YYYY-MM-DD). • (Optional) Estimated effort and actual effort (e.g., in hours or story points). • When a new task is created, it must be appended to tasks.md with status 🟢 Open. The Windsurf AI IDE may offer views to sort/filter tasks by priority, status, or assignee. • Status must be updated as work progresses. If a task is 🔴 Blocked, the reason must be documented clearly in the task description or a dedicated "Blocker Reason" field. • For tasks spanning multiple codebases or repositories, provide cross-repo traceability links and document any special handling in the task entry.

• For comprehensive IAM role and policy authoring, review, and least-privilege best practices, see .iamrolerules.md. • All contributors must follow the IAM role and policy authoring, review, and least-privilege best practices defined in .iamrolerules.md, as well as the organization-wide CI/CD and automation best practices defined in .cicdrules.md.

• All supporting documentation (except this .windsurfrules.md file) must be stored as markdown (.md) files in the docs/ directory at the project root. • Each markdown file in docs/ should cover a specific topic. Recommended standard filenames include: • architecture.md • security_practices.md • user_stories.md • development_workflow.md • onboarding.md • traceability_matrix.md • process_exceptions.md • A README.md within the docs/ folder itself is recommended if the documentation structure becomes complex, explaining the purpose of key documents. • All code refactoring must follow the canonical rules and patterns defined in .refactoringrules.md, which is based on Martin Fowler’s Refactoring Catalog and tailored for this project. • Documentation files must be kept up to date as the project evolves. Changes to documentation should be part of the regular review process. The Windsurf AI IDE may prompt for documentation updates when related code changes are detected. • All documentation and diagrams must be accessible (e.g., include alt text for images/diagrams, use readable tables). • When creating architecture or other diagrams, always use Mermaid syntax for diagram blocks in markdown files (e.g., `mermaid ... ` ). The IDE should offer a preview for Mermaid diagrams.