End-to-End AI-Assisted Development: A Practical Guide using Windsurf Cascade (or similar)

Introduction

The landscape of software development is rapidly evolving, with AI-powered tools becoming increasingly integral to the workflow. These tools, designed to understand code, logic, and even natural language, can significantly boost productivity, accelerate development cycles, and assist in generating high-quality code. This tutorial will guide you through the entire process of building a real application, a Chrome extension, using an AI-assisted coding agent. We’ll demonstrate a complete end-to-end process using Windsurf Cascade, and touch on concepts that are applicable to other similar AI coding tools.

Prerequisites

Before you begin, you should have a basic understanding of the following:

  • Git and GitHub: You should be familiar with version control concepts and have a GitHub account.
  • npm (or similar): You should have a package manager installed and be familiar with its basic usage.

It’s also helpful (but not mandatory) to have:

  • JavaScript Framework Architecture: Basic knowledge of how JavaScript application frameworks like React are structured.
  • Build Processes: A basic grasp of how build tools like npm and Vite work.
  • APIs: Familiarity with the APIs you plan to use in your project (e.g., Chrome Extension APIs).
  • Runtime Environment: Understanding of the environment where your application will run (e.g., browser, Chrome extension, mobile device, etc.).

Tutorial Steps

1. Project Setup

  • Action: Begin by generating a basic front-end project. In this case we will use bolt, a project scaffolding tool.
  • Explanation: Project scaffolding with templates is used to quickly initialize a project with a pre-configured structure and necessary files. In our case we will use bolt.new command, but any tool that creates a react + typescript app should work.
  • Outcome: A basic front-end project is created with a package.json, src, and other files and folders. The front-end app will use React + Typescript.

2. Gathering Relevant Documentation

  • Action: Gather all relevant documentation, code examples, and front-end files. This could include API documentation, code snippets from tutorials, and any existing project files.
  • Explanation: Providing the AI coding agent with comprehensive documentation is crucial for effective context and guidance. By compiling all the relevant code, we ensure that it has all necessary context.
  • Outcome: All relevant documentation, code examples and front-end files are compiled and available for future use, in a single file.

3. Initializing the Git Repository and Adding Files

  • Action: Create a new repository on GitHub and add all initial project files to the repo using git commands.
  • Explanation: Version control using git allows you to track all the changes of your projects, and also to backup your project on a remote server, allowing you to easily collaborate with others.
  • Outcome: A git repository is initialised, and all the files are uploaded to the remote server, ready for development.

4. Compiling all docs within the repo into a single file:

  • Action: Use the gitingest command (or similar) to combine all documentation and code files into one large text file, to serve as a single source of truth to the agent.
  • Explanation: By compiling all the required code into a single document, it simplifies the process for the AI to understand and reason over the project requirements and context.
  • Outcome: All files are properly ingested into a single file, ready to be supplied to the AI coding agent.

5. Initial AI Interaction and Development Plan Generation

  • Action: Now, provide the single, compiled file to your AI coding agent (e.g., Gemini). Ask it to generate a development plan based on the context.
  • Explanation: By providing a single, large document, we give the LLM an overview of our project, and it can use that to give us a detailed development plan.
  • Outcome: An initial development plan is generated by the AI coding agent.
  • Example Prompt: "Here’s a file containing all the documentation, code examples, and front-end files for a project. Review the file and generate a development plan to complete the project. The goal is to create a chrome extension that converts webpages to markdown, save them, and manage them in collections."

6. Review and Refine the Plan (Phase 1)

  • Action: Carefully review the initial plan. You may find that some elements are missing, such as unit testing, or a strategy to manage state. Ask the AI coding agent to add these missing elements.
  • Explanation: Always thoroughly review and scrutinize the AI generated plan, to ensure all necessary steps are present to reduce problems during development.
  • Outcome: A revised development plan that includes unit testing, and a potential integration testing strategy.
  • Example Prompt: "This is a great start. Can you add unit tests for each step of the plan, and suggest an integration testing strategy, so that all pieces of the application work together?"

7. Review and Refine the Plan (Phase 2)

  • Action: Now review the revised plan. Make sure that the plan makes sense, that there are no glaring errors, and that it is complete with all necessary steps. If anything is missing, provide additional documentation and ask the AI to update the plan accordingly.
  • Explanation: At this stage, the plan should be scrutinized carefully to ensure that there are no flaws. By ensuring this, we reduce development issues.
  • Outcome: A final, highly detailed and complete development plan is generated.
  • Example Prompt: "The plan is much better, however can you verify the steps to ensure all the files are created, the chrome api is correctly utilized, and that the UI elements function as expected? I’ve also attached the documentation for chrome.sidePanel, and ui components in chrome extensions. Please ensure that the sidepanel is created properly for the chrome extension.”

8. Execution: Task 1

  • Action: Begin the development phase by completing the first task outlined in the development plan (e.g. setting up the initial manifest file).
  • Explanation: Use the AI to guide you through the execution phase, by focusing on the first step.
  • Outcome: The initial task is successfully completed, and a basic manifest file is generated.

9. AI Interaction and Context

  • Action: Before each conversation with the AI, provide context about the current project status.
  • Explanation: Maintaining context enables the AI to understand the current state of the project, and use all previous steps to guide the user.
  • Outcome: The AI understands the current context of the project, and uses it to assist the development.
  • Example Prompt: “Within the root directory, I have initialized a new repo for the markdown converter application. Within the root directory, you can find the manifest file. The goal is to create a chrome extension that converts webpages to markdown, save them, and manage them in collections. The first task is to create the basic manifest file. Can you do this?”

10. Task Completion

  • Action: Collaborate with the AI coding assistant to complete the current task following the detailed steps provided in the plan.
  • Explanation: By carefully working with the AI you will be able to complete the steps of the development plan, in an iterative approach.
  • Outcome: Task is successfully completed, and necessary files or code snippets have been generated.

11. Unit and Integration Testing

  • Action: Run the unit and integration test cases to verify that the code is working properly. Work with the AI to fix any issues that arise.
  • Explanation: Testing is a crucial part of the development process, to ensure the quality of the project.
  • Outcome: All test cases have passed, and any bugs have been fixed.

12. Build Script Execution (if needed)

  • Action: Run the build script of the project. In our case, we will use npm run build.
  • Explanation: Some projects require a build process to transform the code into a final version.
  • Outcome: The code is successfully built, and is ready to be deployed.

13. Documentation and Changelog

  • Action: Now, after successfully completing the first task, ask the AI to generate the initial documentation such as README.md, BUGS.md (if any) and CHANGELOG.md files.
  • Explanation: Maintaining project documentation is important for the maintainability and the overall quality of the project.
  • Outcome: The necessary documentation files are created, describing the state of the current project.
  • Example Prompt: “The manifest file has now been generated. Can you generate and populate a README.md, BUGS.md (if any), and CHANGELOG.md file? The current project’s goal is to create a chrome extension that converts webpages to markdown, save them, and manage them in collections. So far, the manifest file has been created, and the project’s git repository has been initialised.”

14. Git Ignore
* Action: Now add any unnecessary files to the .gitignore file, such as node modules folder, build folder, and any other files that are not required to be uploaded to the git repository.
* Explanation: By having a solid .gitignore file you will ensure that the remote repository does not contain any unnecessary files, making the repo cleaner and easier to maintain.
* Outcome: No unnecessary files are added to the git repository.

15. Commit Message
* Action: Ask the AI to create a commit message based on the current changelog file.
* Explanation: A clear commit message helps to clarify the changes in the git repo, as it documents changes made for every commit.
* Outcome: A properly formatted git commit message is generated.
* Example Prompt: “Here’s the current CHANGELOG.md file. Create a commit message summarizing the latest version using this file.”

16. Git Commit and Push

  • Action: Use the git commands to add all files, commit with the generated commit message, and push to the remote server.
  • Explanation: By pushing to the remote server, the latest state of the project is available to the team.
  • Outcome: All the new files have been uploaded to github, and the commit has been properly pushed to the remote repository.

17. Repeat Steps 8-16

  • Action: For each of the steps in the plan, repeat steps 8 to 16.
  • Explanation: In an iterative fashion, create your application, by following steps 8 to 16 until the project is fully completed.
  • Outcome: The entire project has been completed.

Conclusion

This tutorial has demonstrated how to develop an application from beginning to end with the assistance of an AI coding agent. We've explored the iterative nature of AI-assisted development, emphasizing the importance of planning, detailed instructions, continuous testing, and thorough documentation. Tools like Windsurf Cascade (or similar) can significantly streamline the development process, allowing developers to achieve more with less effort.

AI-assisted development is not a silver bullet but a powerful tool that, when used correctly, can drastically improve your coding workflow. We encourage you to experiment with AI tools and explore the different features of each tool, and build your own amazing applications.

Resources

This article should serve as a great resource for anyone wanting to get started with AI-assisted development. Let me know if you have any other questions or want me to make further adjustments!