Development Workflow Prompts (6 Phases + Master)

01_starting_phase_prompt.md

Starting Phase: Setup and Task Acquisition

Goal: To prepare your development environment, retrieve all necessary task details, and create a dedicated feature branch, ensuring you are ready to begin the Researching Phase.

Phase Starts: When a new Jira ticket is assigned, a new task is identified, or when a user suggests a large feature to build. Phase Ends: When you have a clean, up-to-date feature branch with all necessary ticket information loaded, and the ticket (if applicable) is moved to "In Progress" and assigned to you.

Expected Artifacts:

• Local repository on the correct feature branch.
• Feature branch correctly named and ideally pushed to the remote repository.
• Task or Jira ticket details (ID, summary, description, acceptance criteria) fetched and available (e.g., stored in .agent/[JIRA-TICKET_OR_TASK-NAME]/task_details.md if extensive).
• Jira ticket status updated to "In Progress" and assigned to the current user (if a Jira ticket is involved).

Steps:

1. Check for Unstaged Changes:

   • If unstaged changes exist, ask the user whether to stash, commit, or revert them before proceeding.

2. Switch to Primary Branch:

   • Determine if the repository uses main, master, or another primary branch.
   • Checkout the appropriate primary branch (e.g., git checkout main).

3. Update Codebase and Dependencies:

   • Pull the latest changes from the remote primary branch (e.g., git pull origin main).
   • Identify the package manager (pnpm, yarn, npm) based on lock files (prioritize pnpm).
   • Install or update dependencies using the appropriate command (e.g., pnpm install).

4. Get Jira Ticket Details (or Task Definition):

   • If not already provided, obtain the Jira ticket ID or a clear definition/name for the task/feature.
   • Use tools at your disposal to retrieve full information about the specified ticket (summary, description, acceptance criteria, current status, assignee) or to clearly document the user-suggested feature.
   • If the details are extensive, consider saving them to a file like .agent/[JIRA-TICKET_OR_TASK-NAME]/task_details.md.

5. Update Jira Ticket Status and Assignment (if applicable):

   • If a Jira ticket is involved, use tools at your disposal to:
     • Assign the ticket to the current user (e.g., "current_user").
     • Update the ticket status to "In Progress".

6. Create Feature Branch:

   • The branch name MUST follow the format: {type}/{JIRA-KEY}-{description}.
     • Example: feat/DX-123-add-user-login
   • Valid types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test.
   • The {JIRA-KEY} should be the full ticket ID (e.g., DX-123) or a short, descriptive task name if no Jira ticket exists.
   • The {description} should be a short, kebab-case summary of the task.
   • Create and checkout the new branch (e.g., git checkout -b feat/DX-123-add-user-login).
   • Optional but recommended: Push the new branch to the remote repository (e.g., using VCS commands like git push -u origin feat/DX-123-add-user-login).

This phase is now complete. You MUST finish this phase now and do not move on to the next phase.

02_researching_phase_prompt.md

Researching Phase: Information Gathering and Analysis

Goal: To thoroughly understand the task requirements, explore the existing codebase and relevant documentation, identify potential challenges, and gather all necessary information to create a robust implementation plan.

Phase Starts: After the Starting Phase is complete. You have a dedicated feature branch and the initial Jira ticket details or task definition. Phase Ends: When you have a comprehensive understanding of the problem, the context, and potential solution paths. Key findings are documented.

Expected Artifacts:

• A collection of notes and findings stored in .agent/[JIRA-TICKET_OR_TASK-NAME]/research_notes.md. This includes:
  • List of relevant files, modules, and functions.
  • Potential approaches considered.
  • Identified dependencies, risks, and ambiguities.
  • Links to relevant documentation or external resources.
  • Any clarifying questions for stakeholders.

Steps:

1. Deep Dive into Requirements:

   • Re-read the Jira ticket description, acceptance criteria, and any linked documents.
   • Identify any ambiguities or missing information. Formulate questions for stakeholders if needed.

2. Explore Existing Codebase:

   • Use tools for semantic codebase search to understand relevant modules and functionalities.
   • Employ tools for pattern-based text search (like regex search) for finding specific functions, variables, error messages, or patterns.
   • Trace execution paths related to the task.
   • Analyze related components and their interactions. Note down any existing patterns or conventions in the areas you'll be working.

3. Consult Documentation:

   • Search internal documentation (e.g., Confluence, existing Markdown files in the repo) using tools available for querying documentation stores.
   • Look for architectural diagrams, design documents, API specifications, or style guides relevant to the task.
   • Use web search tools for information on external libraries, technologies, specific error messages, or general problem-solving techniques.

4. Leverage Knowledge Bases:

   • Utilize tools at your disposal to query internal knowledge bases for company-specific information, internal best practices, or solutions to similar past problems.

5. Synthesize and Document Findings:

   • Consolidate all gathered information.
   • Identify potential challenges, dependencies, and edge cases.
   • Outline 1-2 high-level approaches if they emerge.
   • Document your findings in .agent/[JIRA-TICKET_OR_TASK-NAME]/research_notes.md. This documentation will be crucial for the Planning Phase.

This phase is now complete. You MUST finish this phase now and do not move on to the next phase.

03_planning_phase_prompt.md

Planning Phase: Creating the Implementation Blueprint

Goal: To translate the research findings and task requirements into a clear, actionable, and detailed implementation plan. This plan will guide the Coding Phase.

Phase Starts: After the Researching Phase is complete. You have documented research findings and a good understanding of the task. Phase Ends: When a comprehensive implementation plan is created, documented, and ideally reviewed (e.g., by a peer or yourself after a short break).

Expected Artifacts:

• A detailed implementation plan document, saved as .agent/[JIRA-TICKET_OR_TASK-NAME]/plan.md. This plan should include:
  • Overview/Goals: What the task aims to achieve, including constraints.
  • Analysis Summary: Key insights from the Research Phase.
  • Technical Approach: Chosen technologies, patterns, and high-level design. Pseudocode for complex logic if helpful.
  • Implementation Steps: A breakdown of the work into concrete, actionable tasks or phases.
  • Checklist of Tasks: Including steps for coding, testing (unit, integration), and documentation updates.
  • Test Verification Strategy: How each part of the implementation will be tested.

Steps (You are an expert software architect guiding this process):

1. Review Research Artifacts & Requirements:

   • Thoroughly review the Jira ticket (description, acceptance criteria) and your research notes/document from the previous phase.
   • Ensure all questions from the research phase have been addressed or are noted as assumptions.

2. Define Technical Approach:

   • Based on research, select the most appropriate technical approach.
   • Specify any new technologies, libraries, or patterns to be used, or how existing ones will be leveraged.
   • Outline the high-level design of the solution. Consider data structures, main components, and their interactions.

3. Break Down Implementation:

   • Divide the work into logical, manageable steps or phases.
   • For each step/phase:
     • Define clear sub-tasks.
     • Estimate effort roughly (optional, but can be helpful).
     • Identify any dependencies between tasks.

4. Develop Test Strategy:

   • For each major piece of functionality or sub-task, define how it will be tested.
   • Specify if unit tests, integration tests, or manual verification steps are needed.

5. Create Implementation Plan Document:

   • Structure the plan as follows (save to .agent/[JIRA-TICKET_OR_TASK-NAME]/plan.md):

     # Plan: [Jira Ticket ID or Task Name] - [Short Task Description]
     
     ## 1. Overview
     *   **Goal:** (Briefly state the main objective of this ticket)
     *   **Jira Ticket:** [Link to Jira Ticket]
     *   **Constraints/Key Requirements:** (List any critical constraints or non-functional requirements)
     
     ## 2. Analysis Summary
     (Summarize key findings from the Research Phase: relevant files, potential challenges, important context)
     
     ## 3. Technical Approach
     (Describe the chosen solution: architecture, patterns, libraries, key algorithms, pseudocode for complex parts)
     
     ## 4. Implementation Steps
     (Breakdown into phases if complex, otherwise a list of detailed tasks)
     
     ### Phase 1: [Name of Phase 1 or "Core Logic"]
     *   **Goal:** [Goal of this phase]
     *   **Tasks:**
         *   [ ] Task 1.1: (Description, estimated effort)
         *   [ ] Task 1.2: (Description, estimated effort)
     *   **Test Verification:** (How will this phase/set of tasks be tested? e.g., "Unit tests for X, Y, Z functions", "Manual verification of UI flow A")
     
     ### Phase 2: [Name of Phase 2 or "Integration & Refinements"] (If applicable)
     *   **Goal:** [Goal of this phase]
     *   **Tasks:**
         *   [ ] Task 2.1: (Description, estimated effort)
     *   **Test Verification:** (How will this phase/set of tasks be tested?)
     
     ## 5. Checklist for Completion
     *   [ ] All core logic implemented as per plan.
     *   [ ] Unit tests written and passing for new/modified code.
     *   [ ] Integration tests (if applicable) written and passing.
     *   [ ] Code adheres to style guides and best practices.
     *   [ ] Necessary documentation (code comments, README updates, user guides) created or updated.
     *   [ ] Manual verification of key user flows successful.
     *   [ ] Jira ticket updated with progress/notes.

6. Review Plan:

   • Read through the complete plan. Does it make sense? Is it actionable? Are there any gaps?
   • (Self-correction step) Ask yourself 2-3 critical questions about the plan to ensure robustness before starting coding. Example: "What is the biggest risk in this plan?", "Is there a simpler alternative I missed?"

This phase is now complete. You MUST finish this phase now and do not move on to the next phase.

04_coding_phase_prompt.md

Coding Phase: Implementation and Unit Testing

Goal: To translate the approved implementation plan into working, high-quality, and unit-tested code, including necessary documentation updates.

Phase Starts: After the Planning Phase is complete and you have a detailed implementation plan (.agent/[JIRA-TICKET_OR_TASK-NAME]/plan.md). Phase Ends: When all planned code is written, all unit tests for the new/modified code are passing, relevant documentation is updated, and the changes are committed locally to the feature branch.

Expected Artifacts:

• Functional code implementing all features/fixes outlined in the plan.
• A suite of passing unit tests covering the new and modified code.
• Updated or newly created documentation (code comments, READMEs, user guides as planned).
• All changes are locally committed to the feature branch with clear, atomic commit messages.
• The checklist in the .agent/[JIRA-TICKET_OR_TASK-NAME]/plan.md is updated to reflect completed coding, unit testing, and documentation tasks.

Steps:

1. Understand the Plan:

   • Thoroughly review the implementation plan from .agent/[JIRA-TICKET_OR_TASK-NAME]/plan.md.
   • Ensure you understand each task and its expected outcome.

2. Implement Task by Task:

   • Work through the tasks outlined in the plan.
   • Use a file editing tool for making code changes. Provide sufficient context and clear instructions for each edit.
   • Focus on one task or a small group of related tasks at a time.

3. Adhere to Conventions and Quality Standards:

   • Follow the project's established coding style, naming conventions, and architectural patterns. Refer to existing code, CONTRIBUTING.md, or style guides.
   • Write clear, maintainable, and efficient code. Use meaningful variable and function names.
   • Break down complex logic into smaller, manageable functions/modules.

4. Write Unit Tests Concurrently:

   • For each new function, module, or significant piece of logic, write corresponding unit tests.
   • Unit tests should primarily focus on expected inputs and outputs of the code being tested.
   • Avoid mocking the actual code implementation.
   • Mocking should be reserved ONLY for external HTTP calls or external packages/libraries if direct usage is problematic or introduces instability to the tests. Prefer not to mock if possible.
   • Aim for good test coverage. Tests should verify correctness for expected inputs, edge cases, and error conditions.

5. Iterate and Test:

   • Test your changes frequently during development, not just at the end of a task.
   • Perform manual testing for UI changes or complex workflows if applicable, as outlined in your plan's test verification strategy.

6. Generate and Update Documentation:

   • As per the plan, create new documentation (e.g., for new features, API endpoints) or update existing documentation (code comments, READMEs, user guides) to reflect the changes made.
   • Ensure documentation is clear, accurate, and helps others understand and use the new/modified code.

7. Commit Best Practices:

   • Commit your changes locally after completing a logical unit of work (e.g., a single task or a small group of related tasks from the plan, including its tests and documentation updates).
   • Write clear, concise, and atomic commit messages. Reference the Jira ticket ID in your commit messages (e.g., feat(DX-123): Implement user authentication).
   • Ensure all tests (unit and any relevant integration/build checks) are passing before each commit.

8. Update Plan Checklist:

   • As you complete tasks related to coding, unit testing, and documentation, update the checklist in your .agent/[JIRA-TICKET_OR_TASK-NAME]/plan.md.

This phase is now complete. The code is implemented, unit tested, documented, and committed locally. You MUST finish this phase now and do not move on to the next phase.

05_committing_phase_prompt.md

Committing Phase: Code Freeze, PR, and Review

Goal: To finalize the code, create a well-documented Pull Request (PR), facilitate code review, and prepare for potential refinements or merging.

Phase Starts: After the Coding Phase is complete. All code is written, unit tested, documented, and all local commits are on the feature branch. Phase Ends: When the Pull Request is created, reviewers are notified/suggested, and the Jira ticket (if applicable) is updated to reflect "In Review" status. The process then awaits reviewer feedback, potentially leading to the Refining Phase.

Expected Artifacts:

• Feature branch pushed to the remote repository with all commits.
• A Pull Request created on the code hosting platform (e.g., GitHub) with a comprehensive description.
• Reviewers identified/suggested.
• Jira ticket (if applicable) updated to "In Review" status.
• The checklist in .agent/[JIRA-TICKET_OR_TASK-NAME]/plan.md updated.

Steps (You are a Pull Request specialist guiding this):

1. Final Checks & Code Freeze:

   • Ensure all tasks in the .agent/[JIRA-TICKET_OR_TASK-NAME]/plan.md checklist (related to coding, unit tests, documentation, and local commits) are complete.
   • Run all project tests (unit, integration, end-to-end if applicable) one last time to ensure everything passes.
   • Run linters and formatters to ensure code style compliance.
   • Consider this a "code freeze" for the feature; further changes should ideally only address review feedback.

2. Push Changes:

   • If not already done, push your feature branch with all its local commits to the remote repository (e.g., using VCS commands like git push origin feat/DX-123-add-user-login).

3. Prepare PR Information:

   • Identify Target Branch: Determine the correct primary branch for the PR (e.g., main, develop).
   • Gather Diff: Obtain a diff of your changes against the target branch to summarize. You can use VCS diffing tools for this (e.g., git diff $(git merge-base origin/main HEAD) -- . ":('''exclude''')pnpm-lock.yaml" ":('''exclude''')package-lock.json" ":('''exclude''')yarn.lock", adjusting the target branch as needed).
   • Review Commit Messages: Ensure your commit messages are clear and will help in understanding the PR.

4. Create Pull Request:

   • Use tools available for interacting with your code hosting platform to create the Pull Request (e.g., a specific CLI command or an MCP tool).
   • Set the base branch to the correct target branch and the compare branch to your feature branch.

5. Write PR Description:

   • The PR description is crucial for reviewers. Use the following Markdown structure. (This is based on the create_or_modify_pr_instructions task).

     ### Description:
     (Summarize the motivation for the change in 1-2 sentences. Start with an action verb, e.g., Fixes, Enhances, Refactors. Do not mention the project name or that this is a pull request. Reference the Jira ticket, e.g., "Fixes DX-123 by...")
     
     ### Type of Changes:
     (List the main changes made, focusing on the most impactful ones. Limit to 2-3 concise bullet points. If there are other changes, mention them in the notes.)
     *   [Change 1]
     *   [Change 2]
     
     ### How can it be used:
     (Briefly describe the effect of the changes. Include short code snippets if relevant, enclosed in triple backticks.)
     
     ### How did you test it:
     (Mention the testing methods used: unit tests, integration tests, manual verification steps as per the plan. Explain how these tests validate the changes. Reference the plan's test verification section.)
     
     ### Notes for the reviewer:
     (Provide any additional important information in 1-2 sentences. Highlight any areas needing special attention, known limitations, or follow-up work. Link to the `.agent/[JIRA-TICKET_OR_TASK-NAME]/plan.md` for detailed planning context.)

6. Suggest Reviewers & Link Jira Ticket:

   • Suggest appropriate reviewers. To do this, use VCS history exploration tools to identify committers who have recently modified the files changed in this PR. Also, consider team leads or subject matter experts.
   • If a Jira ticket is involved, ensure the PR is linked to it (many platforms offer automation if commit messages or PR titles include the ticket ID).
   • Update the Jira ticket with a link to the PR and move its status to "In Review" (or equivalent).

7. Update Plan Checklist:

   • Update the checklist in your .agent/[JIRA-TICKET_OR_TASK-NAME]/plan.md to reflect PR creation.

This phase is now complete. You MUST finish this phase now and do not move on to the next phase. Await reviewer feedback, which may lead to the Refining Phase.

06_refining_phase_prompt.md

Refining Phase: Addressing PR Feedback

Goal: To systematically address feedback received on a Pull Request (PR), implement necessary changes, and prepare the PR for re-review and merging.

Phase Starts: When actionable feedback (comments requiring code changes or clarifications) is provided on an open PR. Phase Ends: When all agreed-upon feedback has been addressed, changes are committed and pushed, and reviewers are notified of the updates. The PR is then ready for a final review and merge.

Expected Artifacts:

• An updated feature branch with new commits addressing the PR feedback.
• A plan for addressing feedback, potentially documented in .agent/[JIRA-TICKET_OR_TASK-NAME]/refinement_plan.md.
• Comments on the PR indicating how feedback was addressed.
• Reviewers notified of the updates.

Steps (You are a diligent developer refining your work):

1. Fetch and Review PR Comments:

   • Use tools at your disposal to fetch all new comments from the Pull Request.
   • Carefully read each comment to understand the reviewer's concerns or suggestions.

2. Plan Feedback Addressal:

   • For each piece of actionable feedback, determine the necessary changes.
   • If the feedback is extensive or requires significant changes, create a small plan. This can be a checklist or a brief document in .agent/[JIRA-TICKET_OR_TASK-NAME]/refinement_plan.md.
   • Prioritize the feedback if there are multiple points.

3. Communicate Plan (If Necessary):

   • If the feedback is ambiguous, requires major architectural changes, or you disagree with a suggestion, discuss it with the reviewer via PR comments before implementing.
   • For straightforward changes, you can proceed directly to implementation. Inform the user (your pair programmer) about the plan to address the comments.

4. Implement Changes:

   • Make the necessary code modifications based on the feedback and your plan.
   • Follow the same coding standards and unit testing guidelines as in the Coding Phase:
     • Unit tests should primarily focus on expected inputs and outputs.
     • Avoid mocking actual code implementation. Mock only external HTTP calls or external packages if necessary.
   • Update or add new unit tests as needed to cover the changes.
   • Update any relevant documentation (code comments, READMEs) affected by the changes.

5. Test Changes:

   • Run all relevant unit tests to ensure they pass.
   • Perform any manual verification if the changes affect user-facing behavior.

6. Commit and Push Changes:

   • Commit the changes with clear messages indicating they are in response to PR feedback (e.g., "fix: Address PR feedback on user validation").
   • Push the updated feature branch to the remote repository.

7. Respond to Comments and Notify Reviewers:

   • On the PR, reply to each feedback comment explaining how it was addressed or why a different approach was taken.
   • After all feedback is addressed and changes are pushed, formally re-request review or notify the reviewers that the PR has been updated.

This phase is now complete. You MUST finish this phase now and do not move on to the next phase. The PR is updated and awaiting final review.

master_workflow_prompt.md

Master Development Workflow

This project follows a six-stage development workflow. Adherence ensures consistency and quality. Consult linked prompts for full details on goals, start/end points, artifacts, and steps for each phase.

Workflow Diagram

graph TD
    A[1. Starting] --> B("Artifact: Ready Branch and Task Details");
    B --> C[2. Researching];
    C --> D("Artifact: Research Notes");
    D --> E[3. Planning];
    E --> F("Artifact: Implementation Plan .md");
    F --> G[4. Coding];
    G --> H("Artifact: Code, Unit Tests, Docs, Local Commits");
    H --> I[5. Committing];
    I --> J("Artifact: PR Created");
    J --> K{Feedback?};
    K -- Yes --> L[6. Refining];
    L --> M("Artifact: Feedback Addressed and Branch Updated");
    M --> J;
    K -- No/Approved --> N((Merged));

    classDef phase fill:#D5F5E3,stroke:#1ABC9C,stroke-width:2px;
    classDef artifact fill:#EBF5FB,stroke:#3498DB,stroke-width:1px,color:#333;
    classDef decision fill:#FDF3E7,stroke:#F39C12,stroke-width:2px;
    classDef merged fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    class A,C,E,G,I,L phase;
    class B,D,F,H,J,M artifact;
    class K decision;
    class N merged;

Loading

Phase Details:

1. Starting Phase: Setup & Task Acquisition

   • Ends with: Ready feature branch, task details documented (e.g., in .agent/[JIRA-TICKET_OR_TASK-NAME]/task_details.md).
   • Instructions: prompts/01_starting_phase_prompt.md

2. Researching Phase: Info Gathering & Analysis

   • Ends with: Documented findings in .agent/[JIRA-TICKET_OR_TASK-NAME]/research_notes.md.
   • Instructions: prompts/02_researching_phase_prompt.md

3. Planning Phase: Creating Implementation Blueprint

   • Ends with: Detailed plan in .agent/[JIRA-TICKET_OR_TASK-NAME]/plan.md.
   • Instructions: prompts/03_planning_phase_prompt.md

4. Coding Phase: Implementation, Unit Testing & Docs

   • Ends with: Coded features, passing unit tests, updated docs, all locally committed.
   • Instructions: prompts/04_coding_phase_prompt.md

5. Committing Phase: PR Creation & Initial Review Request

   • Ends with: PR created, reviewers suggested, Jira updated (if applicable).
   • Instructions: prompts/05_committing_phase_prompt.md

6. Refining Phase: Addressing PR Feedback

   • Objective: Systematically address PR feedback, implement changes, and prepare for re-review.
   • Ends with: Feedback addressed, changes pushed, reviewers notified. PR ready for final review/merge.
   • Instructions: prompts/06_refining_phase_prompt.md

Each phase prompt concludes with an instruction to complete the current phase before moving to the next.