Sam is your personal AI assistant for code generation that empowers yourself. The goal of SAM is to support developers in building better coding practices by providing structured, AI-generated guidance for implementing GitHub issues, helping users engage in the coding process while avoiding reliance on automated code completion. SAM promotes responsible AI use and skill development, making it an educational tool embedded directly within the VSCode environment.

SAM is a VSCode extension that connects to the user’s GitHub account, retrieves user stories and issues, and presents them in a convenient sidebar. Users can select an issue to receive AI-generated, natural-language guidance that outlines structured steps for implementing the solution. SAM’s primary focus is on enhancing learning and promoting responsible AI use by guiding users through the development process without doing all the work for them, while also promoting good software engineering practices.

SAM's main audience are students and developers looking to grow their skills responsibly by engaging with AI as a supportive assistant, not a shortcut. The tool provides actionable guidance that encourages the adoption of good software engineering practices while reinforcing core skills. SAM is positioned as an educational tool that prioritizes mastery over quick wins, helping users build a sustainable foundation of development knowledge.

The key advantages of using SAM fosters skill-building by guiding users in practical steps aligned with sound development practices. The AI is an assistant, not an automator, encouraging active learning and accountability. By integrating seamlessly with GitHub and VSCode, SAM fits naturally into developers’ existing workflows and provides an intuitive and educational AI experience.

Ultimately, SAM’s goal is to enhance coding skills through structured AI guidance, balancing productivity with learning, and supporting developers as they grow in their coding journey.

To refine SAM’s approach, we examined two well-established tools: GitHub Copilot and ChatGPT, both popular for their AI-assisted coding capabilities yet limited in fostering active learning and engagement.

GitHub Copilot stands out for its in-line code completion, providing quick solutions to coding tasks. However, many users report that they end up accepting suggestions automatically, pressing "Tab" repeatedly without fully engaging in the problem-solving process. Because Copilot directly inserts code, it can act as a “spoiler,” revealing answers that limit its utility for those looking to genuinely learn.

ChatGPT, on the other hand, provides rich, detailed guidance in natural language, making it an effective assistant for learning. However, the experience is hindered by the need to switch between ChatGPT’s interface and the coding environment, often requiring users to copy and paste content across windows, which can be disruptive to the coding flow.

SAM bridges these gaps by combining the strengths of both tools: it integrates seamlessly within the editor, eliminating workflow interruptions, and offers thoughtful, step-by-step guidance in response to selected issues. Rather than providing direct code completions, SAM’s structured assistance keeps users engaged in the coding process, empowering them to learn and build confidently while making responsible use of AI.

Include high-level class diagram with key domain concepts. Complement this diagram with other high-level diagrams has appropriate (activity, sequence, etc.).

SAM is built with a client-server architecture, consisting of a front-end VSCode extension and a back-end Go server. The front-end uses React with TypeScript, providing an interactive interface within VSCode where users can view GitHub issues and access AI-generated guidance. This UI is responsive and integrated directly into the editor, ensuring smooth user interactions.

The back-end Go server manages API communications:

1. It interacts with the GitHub API to fetch user stories and issues, keeping the displayed information current.
2. It connects to the Gemini API for AI-generated, step-by-step guidance aligned with software engineering practices.

For portability, the back-end runs inside a Docker container, making it easy to deploy across different environments. This architecture supports a modular design where the front-end provides an intuitive experience and the back-end efficiently handles data processing, enabling SAM to deliver contextual AI guidance within the editor.

Technologies

SAM uses several key technologies, with a mix of client-imposed and team-driven choices. The client-restricted technology is Docker, as the back-end service must be portable and easily integrable with other services via REST APIs. This ensures that SAM’s back-end can be reliably deployed and scaled across different environments.

For the front-end, we chose React with TypeScript for its excellent developer experience and flexibility in creating a responsive, maintainable UI within VSCode. This combination allows for fast development and easy integration with VSCode's extension architecture.

For the back-end, we selected Go due to its simplicity, high performance, and strong support for concurrency, making it an ideal choice for handling API requests. Additionally, Go integrates well with the Gemini API through the Go Google Genai Package, allowing us to seamlessly provide AI-generated guidance.

In Sprint 0, we implemented a prototype that focused on setting up both a simple front-end to test that we can actually create interactive interfaces in VSCode and a simple Go back-end to test that we can in fact fetch the issue list from a GitHub repository and provide it to the Gemini agent, together with the code for context, and verify that it solves the problem in natural language. In the future we need to integrate all the services together and solve the problems that may arise from that.

To contribute to SAM, you’ll need to set up both the front-end (VSCode extension) and back-end (Go server) locally. You can follow these steps to get everything running in a development environment.

1. Install Node.js and npm - Required to build and run the front-end.
2. Install Go - Required to build and run the back-end.
3. Docker - To containerize and test the back-end, if desired.

cd frontend
npm install

After this you need to open the entire project folder in VSCode. In the root directory, run

npx esbuild ./src/extension.ts --bundle --platform=node --outfile=./dist/extension.js --external:vscode

Then, inside VSCode, open extension.ts and press F5 (or go to Run and Debug > Start Debugging) to start the front-end as an extension in a new VSCode window. This will open a separate instance of VSCode where SAM’s extension will be active, allowing you to interact with it as a user would.

cd backend
go mod tidy
go run cmd/server/main.go

In the backend directory, use Docker to build the back-end service:

docker build -t sam-backend .

To start the back-end server in a Docker container:

docker run -p 8080:8080 sam-backend

The API documentation for the back-end, coding conventions and general guidelines will be added soon.

Our extension just reads the repository name and owner and sends it to the backend, after this all the work is processed in the server. This does mean that the extension just works for public GitHub repositories, as we deemed GitHub authentication could be a potential attack vector if not properly handled. The only concern a user may have is that, if they are working in a private repository, the server will receive a message containing the name of that repository, but nothing more, which is acceptable.

Quality is assured through extensive testing of all the functionality of SAM, both manual and automated. We also have setup a build and test (acceptance tests) pipeline using GitHub Actions for our Go server, ensuring that we do not push breaking code to production.

So what is SAM and how to use this AI companion? SAM is designed to provide AI-assisted guidance directly within VSCode, helping you with issue tracking and development tasks in your GitHub projects.

1. Install the Extension:

   • First, ensure you have SAM installed in your VSCode. You can find the extension in the VSCode Marketplace by searching for "SAM" and clicking Install.

2. Open a Git Repository:

   • Make sure the project folder you have open in VSCode is a Git repository with a linked GitHub remote. This lets SAM access the issues associated with your project.

1. Fetching Issues:

   • SAM will connect to your GitHub remote and automatically fetch the list of issues associated with the repository.
   • The issues will appear in a sidebar in VSCode, allowing you to browse through them quickly.

2. Selecting and Requesting Help on an Issue:

   • Click on any issue in the sidebar to open it. You’ll see details of the issue and an option to Ask for Help.
   • When you request help, SAM will generate a guided response with suggested steps to tackle the issue.

3. Interactive Chat for Additional Questions:

   • If you need further clarification or have additional questions, a chat interface will open within VSCode.
   • SAM is designed to answer follow-up questions, provide more details, and help you understand the issue in depth while avoiding giving you the solution immediately, encouraging you to learn and implement solutions yourself.

SAM is capable of:

• Listing the open issues in the GitHub repository of an open project
• Receiving the project source code as context
• Analyzing a given issue and, given the project context, formulate natural language guidelines to implement the feature or solve the problem
• Chatting with the user to further clarify any doubts they may have about the help given

[example]

• What went well

  • The work was well distributed among team members
  • Everyone was able to complete everything successfully, apart from a detail in the extension UI (this is why one of the issues did not go from Done to Done Done Done)
  • PO made a good estimation on what was achievable in this sprint
  • Scrum Master and Devs did a great job implementing the issues proposed

• What went wrong

  • The requirements/specification for the Extension UI should have been elaborated more clearly. The lack of detail regarding this ended up blocking one of the Devs and we did not end up getting the result we wanted

• What went well

  • We were able to complete everything we planned successfully
  • We were able to upload our code to AI4SD repo and develop SAM to Google Cloud!
  • We improved on the Extension UI and moved it from Done (in the last sprint) to Done Done Done
  • PO made a good estimation for this sprint, although it maybe was a bit more conservative than what it needed to be
  • Scrum Master and Devs were able to complete the implementations planned for sprint 2

• What went wrong

  • SAM in Google Cloud could not access his secret key, which must be corrected (because SAM won't do anything useful without the key)
  • Maybe we could have completed more work this sprint if we planned on doing more, because we were able to complete things relatively fast

We’re grateful for your interest in joining the development of SAM! This page has already provided you with an overview of the main aspects of our project. To get started, please connect with our Scrum Master, who will guide you through the process and help identify the areas where your skills can make the most impact, as there are several ways you can contribute. These may include enhancing existing options and expanding our capabilities to support additional programming languages.

• Team 4
  • Marco Vilas Boas (PO)
  • Miguel Garrido
  • João Coutinho
  • Duarte Gonçalves (SM)
  • Inês Almeida