|
| 1 | +# AI Agent Workflow Rules |
| 2 | + |
| 3 | +Whenever you are given a task to modify, refactor, or create ANY files in this project (code, documentation, configuration, makefiles, scripts, YAML, etc.), you MUST strictly follow this 2-step process. Do not skip steps. |
| 4 | + |
| 5 | +## STEP 1: Planning and Documentation |
| 6 | + |
| 7 | +1. Before writing or modifying any project code, create or update a file named `change.md` in the root directory. |
| 8 | +2. In `change.md`, clearly outline: |
| 9 | + - The goal of the task. |
| 10 | + - The files that will be modified or created. |
| 11 | + - A step-by-step technical plan of the exact changes you intend to make. |
| 12 | + - **Note:** `change.md` is gitignored and temporary - it's only used during the current task session for planning purposes. |
| 13 | +3. **CRITICAL INSTRUCTION:** Once you have saved `change.md`, you must **STOP**. Do not write any code. Ask the user: *"I have outlined the plan in change.md. Please review it. Reply with 'APPROVED' to proceed, or let me know what needs to be changed."* |
| 14 | +4. Wait for the user's explicit approval. |
| 15 | + |
| 16 | +## STEP 2: Implementation |
| 17 | + |
| 18 | +1. ONLY after the user explicitly types "APPROVED" (or a clear affirmative), you may begin implementing the steps exactly as outlined in `change.md`. |
| 19 | +2. Do not deviate from the approved plan without asking for permission first. |
| 20 | +3. **Before completing implementation, follow the Review Checklist below**. |
| 21 | + |
| 22 | +### Review Checklist |
| 23 | + |
| 24 | +**IMPORTANT**: This checklist MUST be followed: |
| 25 | +- When implementing changes (after coding, before committing) |
| 26 | +- When performing standalone code reviews (when asked to review code without implementing) |
| 27 | + |
| 28 | +#### Documentation Review |
| 29 | + |
| 30 | +Check if changes require updates to `docs/` files: |
| 31 | +- New features, tasks, or commands |
| 32 | +- Modified behavior or configuration |
| 33 | +- New dependencies or build requirements |
| 34 | +- Changed workflows or processes |
| 35 | +- Update relevant documentation files before proceeding |
| 36 | +- If unsure whether docs need updating, ask the user |
| 37 | + |
| 38 | +#### Manifest Regeneration Review |
| 39 | + |
| 40 | +Check if changes require regenerating YAML manifests: |
| 41 | +- **NEVER hand-edit files in `release/`** (see [YAML Generation](yaml-generation.md)) |
| 42 | +- Run `make generate-yaml-tasks` if changes affect: |
| 43 | + - Files in `templates/` directory |
| 44 | + - Files in `configs/` (Ansible variable files) |
| 45 | + - Task parameters or behavior |
| 46 | + - RBAC requirements in task definitions |
| 47 | +- Run `make generate-pipelines` if changes affect: |
| 48 | + - Files in `templates-pipelines/` directory |
| 49 | + - Pipeline definitions or structure |
| 50 | +- Run `make test-yaml-consistency` to verify YAML is in sync |
| 51 | +- Commit any regenerated YAML files along with code changes |
| 52 | + |
| 53 | +#### Code Quality Review |
| 54 | + |
| 55 | +Verify code meets project standards: |
| 56 | +- Run `make lint` to check code formatting and style |
| 57 | +- Fix any linter issues with `make lint-fix` |
| 58 | +- Ensure all linter checks pass before committing |
| 59 | +- Run `make test` to verify unit tests still pass |
| 60 | +- Address any test failures before proceeding |
| 61 | + |
| 62 | +### After Implementation |
| 63 | + |
| 64 | +Once implementation and the review checklist are complete, **ask the user** if they would like to proceed with committing and pushing the changes to GitHub (STEP 3). Do not automatically proceed to STEP 3 without user confirmation. |
| 65 | + |
| 66 | +## STEP 3: Git Workflow |
| 67 | + |
| 68 | +After successfully implementing the changes: |
| 69 | + |
| 70 | +1. **Create or verify your feature branch**: |
| 71 | + - If you're already on a feature branch for this work, stay on it |
| 72 | + - Otherwise, create a new branch with a descriptive name: |
| 73 | + ```bash |
| 74 | + git checkout -b feature/descriptive-name |
| 75 | + # or |
| 76 | + git checkout -b fix/issue-description |
| 77 | + ``` |
| 78 | + |
| 79 | +2. **Commit changes** following the commit message guidelines: |
| 80 | + - **Format**: `type(scope): description` |
| 81 | + - **Types**: `feat`, `fix`, `docs`, `test`, `build`, `refactor` |
| 82 | + - **Subject line**: Imperative mood, max 72 chars, capitalized, no period |
| 83 | + - **Body**: Wrap at 72 chars, explain what and why |
| 84 | + - **DCO**: Always use `--signoff` |
| 85 | + |
| 86 | + Example: |
| 87 | + ```bash |
| 88 | + git add <files> |
| 89 | + git commit --signoff -m "feat(execute-in-vm): Add support for custom SSH timeout |
| 90 | +
|
| 91 | + Implements configurable SSH timeout parameter to handle slow VM boots. |
| 92 | + Default timeout remains 5 minutes for backwards compatibility." |
| 93 | + ``` |
| 94 | + |
| 95 | +3. **Push to origin**: |
| 96 | + ```bash |
| 97 | + git push origin feature/descriptive-name |
| 98 | + ``` |
| 99 | + |
| 100 | +4. **Inform the user** that the branch has been pushed and provide the branch name for PR creation. |
| 101 | + |
| 102 | +## Jira Task Management |
| 103 | + |
| 104 | +See [AGENTS.md - Jira Task Management](../AGENTS.md#jira-task-management) for instructions on fetching Jira task information. |
| 105 | + |
| 106 | +When working on Jira-related changes, include the task ID and relevant information in `change.md` and commit messages. |
| 107 | + |
| 108 | +## Why This Process? |
| 109 | + |
| 110 | +- **Prevents mistakes**: Plan is reviewed before implementation |
| 111 | +- **Saves time**: Avoids implementing wrong solutions |
| 112 | +- **Builds trust**: User has full visibility and control |
| 113 | +- **Improves quality**: Thoughtful planning leads to better code |
| 114 | + |
| 115 | +## Example Workflow |
| 116 | + |
| 117 | +``` |
| 118 | +User: "Add a new Tekton task for disk snapshot" |
| 119 | +
|
| 120 | +AI: [Creates change.md with detailed plan] |
| 121 | +AI: "I have outlined the plan in change.md. Please review it. |
| 122 | + Reply with 'APPROVED' to proceed, or let me know what needs |
| 123 | + to be changed." |
| 124 | +
|
| 125 | +User: [Reviews change.md, suggests modifications] |
| 126 | +
|
| 127 | +AI: [Updates change.md based on feedback] |
| 128 | +
|
| 129 | +User: "APPROVED" |
| 130 | +
|
| 131 | +AI: [Implements the plan step by step] |
| 132 | +AI: [Creates branch, commits with DCO sign-off, pushes to origin] |
| 133 | +AI: "Changes have been pushed to branch 'feature/disk-snapshot-task'. |
| 134 | + You can now create a PR on GitHub." |
| 135 | +``` |
| 136 | + |
| 137 | +--- |
| 138 | +← Back to [AGENTS.md](../AGENTS.md) | [Documentation Index](../AGENTS.md#documentation) |
0 commit comments