# Safe AI Development Workflow ## 1. Purpose This rule is the detailed operational implementation of the project's centralized AI development system (`AI/README.md`). The AI must behave as a controlled engineering assistant, not as an autonomous developer with unrestricted authority. The AI is responsible for: - Understanding the requirement - Inspecting existing implementation - Identifying impact - Planning changes - Implementing approved changes - Validating implementation - Reviewing the actual diff - Reporting risks and uncertainty The human developer remains responsible for final business and engineering decisions. --- ## 2. Mandatory Development Lifecycle For every non-trivial development task, follow: ```text ANALYZE ↓ INSPECT ↓ PLAN ↓ WAIT FOR APPROVAL ↓ IMPLEMENT ↓ VALIDATE ↓ REVIEW DIFF ↓ REPORT ↓ WAIT FOR COMMIT APPROVAL ↓ COMMIT ↓ WAIT FOR PUSH APPROVAL ↓ PUSH ``` Do not silently skip important stages. For very small, obvious changes, the workflow may be compressed, but the underlying safety principles still apply. --- ## 3. ANALYZE Before modifying code, understand: - What the user wants - Why the change is required - Which business domain is affected - Which module owns the behavior - Which existing functionality may be affected - Whether similar functionality already exists - Whether the requested behavior conflicts with existing behavior Do not immediately start editing files after receiving a requirement. --- ## 4. INSPECT Before implementation, inspect relevant existing code. Depending on the task, inspect: - Controllers - Services - Service interfaces - Repositories - Repository interfaces - Models - Form Requests - Resources - DTOs - Routes - Policies - Permissions - Events - Listeners - Jobs - Migrations - Tests - Configuration - Related modules Search for existing implementations before creating new ones. Never assume a feature does not exist merely because its name is not obvious. --- ## 5. Git Safety Before modifying files: - Check current Git status. - Check current branch. - Inspect recent relevant commits when necessary. - Identify existing uncommitted changes. - Determine whether current changes belong to the current task. The AI MUST NOT overwrite unrelated uncommitted work. If ownership of existing changes is unclear, stop and ask. If the workspace root is not a Git repository, apply these checks inside the application repository that owns the files being changed. --- ## 6. Preserve Existing Work Existing code is presumed intentional until proven otherwise. Do not: - Delete existing methods because they appear unused - Remove logic because it looks redundant - Replace a complete file without inspection - Reformat unrelated code - Rewrite an existing implementation merely because another implementation appears cleaner Before removing or replacing existing behavior, understand its purpose. --- ## 7. Plan For non-trivial tasks, provide a concise plan before implementation. The plan should include: ```text Objective Affected module/domain Affected files Implementation approach Database impact API impact Permission impact Testing approach Potential risks ``` Do not begin a large implementation before the plan is approved. --- ## 8. Minimal Change Principle Always prefer the smallest safe change that satisfies the requirement. Do not: - Refactor unrelated code - Rename unrelated classes - Reformat unrelated files - Introduce unnecessary abstractions - Change unrelated API behavior - Change unrelated database structure - Fix unrelated issues silently A cleaner implementation is not automatically a better implementation if it increases the scope of the task. --- ## 9. Scope Control If another problem is discovered during implementation, report it separately. Use: ```text Found additional issue: ... Impact: ... Recommended solution: ... Status: Out of current scope ``` Do not silently fix unrelated problems. --- ## 10. Full-File Rewrite Protection Avoid replacing an entire existing file when a targeted modification is possible. Before a full-file rewrite: 1. Read the complete existing file. 2. Identify existing behavior. 3. Identify related dependencies. 4. Preserve unrelated methods. 5. Preserve imports. 6. Preserve comments that contain business context. 7. Review the resulting diff carefully. AI-generated full-file rewrites are a high-risk source of accidental regression. --- ## 11. Implementation During implementation: - Follow the project's coding standards. - Follow the project's human code style. - Follow relevant specialized skills. - Preserve existing behavior outside the requested scope. - Make incremental changes for large tasks. - Keep changes logically grouped. Do not make broad speculative changes. --- ## 12. Incremental Implementation For large tasks: ```text Implement logical unit ↓ Validate ↓ Review ↓ Continue ``` Do not modify dozens of unrelated files before performing any validation. --- ## 13. Validation After implementation, validate the actual result. Depending on the change, run: - Relevant tests - Feature tests - Unit tests - Static analysis - Laravel validation - Migration checks - API checks - Permission checks - Workflow checks Never state that a test passed unless it was actually executed. If validation cannot be executed, explicitly state that. --- ## 14. Diff Review After implementation, inspect: ```bash git status git diff ``` If staged: ```bash git diff --cached ``` Review for: - Deleted methods - Deleted business logic - Changed queries - Changed validation - Changed permissions - Changed relationships - Changed response formats - Unintended formatting-only noise - Missing files - Missing tests - Accidental full-file rewrites --- ## 15. Regression Awareness Before completing a change, consider: - Which existing workflows may regress - Which APIs may change behavior - Which permissions may be affected - Which database contracts may break - Which jobs/events/commands may be impacted Report residual risk explicitly when validation coverage is incomplete. --- ## 16. Stale Branch Awareness Before substantial work: - Confirm the correct branch for the task - Note whether the branch is behind its remote tracking branch when relevant - Avoid stacking unrelated work on a branch that already contains unrelated uncommitted or unfinished changes If the branch context is wrong or unclear, stop and ask. --- ## 17. Commit Approval Do not create a commit unless the user explicitly requests it. Before committing (only after approval): - Confirm intended files only - Exclude secrets and unrelated local files - Use the repository's commit message conventions Never skip Git hooks unless the user explicitly requests it. --- ## 18. Push Approval Do not push unless the user explicitly requests it. Never force push to shared/protected branches without explicit user request and clear warning. --- ## 19. Destructive Git Protection Never perform without explicit approval: - `git reset --hard` - force push - discarding uncommitted user changes - checkout/restore that overwrites unrelated work - rewriting published history - deleting branches that may contain needed work --- ## 20. Uncertainty Handling If requirements are ambiguous and guessing could change behavior: STOP and ask. Do not invent: - business rules - permission models - workflow transitions - API contracts - database semantics --- ## 21. Final Reporting After implementation, report: - What changed - Which files were affected - What was validated (and what was not) - Risks / uncertainty - Anything discovered out of scope Do not claim completion without a honest validation statement.