Skip to content

Getting started with the NEO setup

There are two ways to work with NEO. The first is to use a code editor (for example, VSCode) and, from there, work together with your AI assistant (for example, Claude). The second is to work directly with the AI assistant's desktop app (for example, Claude Code Desktop), sharing the project's local folder with it.

Which option should I choose?

Option How you work Choose it if...
A — Editor + AI assistant You install a code editor (VSCode or another one) and, inside it, an AI assistant extension You prefer to see the project files, the generated code, and the chat with the assistant on the same screen
B — Desktop AI assistant You install only the assistant's desktop app (for example, Claude Code Desktop) and point it to the project folder You prefer something simpler, without installing or learning to use a code editor

Throughout this guide, each step indicates whether it applies to (Option A only), (Option B only), or to both equally (when it doesn't say anything). Always follow the steps that match the option you chose.


Step 1. Install VSCode (only if you chose Option A)

The detailed steps are for VSCode, but you can use any editor, for example IntelliJ.

  1. Download it from code.visualstudio.com and follow the installer (next, next, finish).
  2. Open it once it's installed to confirm that it starts correctly.

Step 2. Install your AI assistant

The installation steps depend on the option you chose:

(Option A only)

  1. In VSCode, open the extensions panel (the little squares icon in the left margin, or Ctrl+Shift+X).

The steps below are for Claude Code. If you use Codex or Copilot, install the equivalent extension and follow that tool's own login flow.

  1. Search for "Claude Code for VS Code" and install it.
  2. When you open it for the first time, it will ask you to sign in with your Claude/Anthropic account — follow the login flow it suggests (the browser opens, you confirm, and you go back to VSCode).

(Option B only)

The steps below are for Claude Code. If you use Codex or Copilot, install that agent's own desktop version.

  1. Download it from code.claude.com and follow the installer (next, next, finish).
  2. Open it once it's installed — the first time, it will ask you to sign in with your Claude/Anthropic account; follow the login flow it suggests.

Step 3. Install Git

Git is what lets you download ("clone") the project repositories.

  • Windows: download it from git-scm.com and install it with the default options (this also installs Git Bash, a terminal you'll need later).
  • Mac: it usually comes preinstalled; if not, run xcode-select --install from the Terminal, or download it from git-scm.com.

Check that it's installed: open a terminal (on Windows, search for "Git Bash") and type:

git --version

If it returns a version number, you're all set.


Step 4. Clone the repositories

You'll work with at least two folders, depending on the project:

  1. NEO-releases — where the skills and playbooks live.
  2. The test repository (for example, TechStore's) — where you'll generate and run the tests. It can be the same repository as the application's or, as in many projects, a separate one.

To get the link to a repository, follow these steps:

Go to GitLab — first, you'll need to be given access permissions to the project. Click the repository you want to clone (for example, "NEO-releases"), press the Code button, and copy the "Clone with HTTPS" URL (or "Clone with SSH", if you prefer that option).

Important: it's recommended that both repositories are downloaded at the same level, that is, as subdirectories of the same parent directory.

How you clone them depends on the option you chose:

(Option A only)

To clone the repository in VSCode: Ctrl+Shift+P → type "Git: Clone" (a text field opens at the very top) → paste the repository URL you copied → choose a folder on your computer → Open when it's done. (The same procedure is explained in more detail in last_version.md, section 6.)

(Option B only)

To clone the repository, open a terminal:

  • Windows: search for "Git Bash" in the start menu and open it.
  • Mac: open the Terminal app.

Go to the folder where you want your projects to live (for example, cd Documents) and run:

git clone <repository-URL>

Replace <repository-URL> with the link you copied in the previous step (for example, the "Clone with HTTPS" URL of NEO-releases). Repeat the command for each repository you need to clone (NEO-releases and the test repository).

As mentioned above, both repositories must end up as subdirectories of the same parent directory.


Step 5. Install Node.js and npm

Node.js is the engine Playwright needs in order to run. npm (Node Package Manager) comes included with Node.js — it isn't installed separately.

  1. Download the LTS version (the recommended one, not the "Current" one) from nodejs.org.
  2. Open the installer you downloaded and follow it with the default options (next, next, finish).

Check that it's installed: for this, you need to open a terminal and type a couple of commands. Where you open it depends on the option you chose at the beginning:

(Option A only)

  1. In VSCode, open the integrated terminal from the Terminal → New Terminal menu (or the shortcut Ctrl+`).
  2. Type, one at a time:

    node --version
    npm --version
    

(Option B only)

  1. Open a terminal:
    • Windows: search for "Git Bash" in the start menu and open it.
    • Mac: open the Terminal app.
  2. Type, one at a time:

    node --version
    npm --version
    

Both commands must return a version number. If instead you see a message like "is not recognized as a command" (command not found), close the terminal, open it again (or restart your computer), and try again — sometimes a restart is needed for the system to recognize the new installation.


Step 6. Make the skills available to your AI assistant

With everything above installed, there's one last step left: telling the assistant where the NEO-releases skills are. The assistant doesn't "guess" them on its own — it needs to find them in a specific folder on your computer.

6.1 How it works

Each skill is a folder with a SKILL.md file inside: written instructions so the assistant knows how to do a specific task (read a story, put together a test plan, generate tests, etc.). The NEO-releases repository already comes with all the skills ready — the only thing missing is "connecting" them to the test repository.

When a session starts, your assistant looks for the skills in this folder, inside the test repository:

<test-repository>/.claude/skills/

If you use Codex or Copilot instead of Claude Code, the logic is the same, replacing .claude with .codex or .copilot.

You don't need to copy the files by hand: NEO-releases includes a script that creates a link (symlink) for each skill, pointing to the real folder inside NEO-releases. That way, when the technical team updates a skill and you update your copy of NEO-releases (git pull, see last_version.md), the change shows up on its own, without repeating any step. The script also links the playbooks into .claude/playbooks/ and copies into .claude/rules/ the rules the assistant needs to run them.

There's one script for each operating system. Both are run from the folder of the test repository (not NEO-releases).

On Linux or Mac

1. Open a terminal:

Option A: in VSCode, open the integrated terminal from the Terminal → New Terminal menu (or the shortcut Ctrl+`).

Option B: open the Terminal app.

2. Navigate to the folder of the test repository:

cd /path/to/test-repository

Replace /path/to/test-repository with the real path where you cloned the test repository on your computer.

3. Run the NEO-releases script:

bash <path-to-neo-releases>/symlink-skills-bash.sh

Replace <path-to-neo-releases> with the path where you cloned NEO-releases. If both repositories are in the same parent folder (as recommended in Step 4), it's ../NEO-releases.

To check the result, ls -l .claude/skills/ must list each skill pointing to the NEO-releases folder.

On Windows

1. Open Git Bash as administrator. Windows only allows creating symbolic links with administrator permissions. Search for "Git Bash" in the start menu, right-click it, and choose Run as administrator. VSCode's integrated terminal won't work for this step, unless you opened VSCode as administrator.

2. Navigate to the folder of the test repository:

cd /path/to/test-repository

3. Run the NEO-releases script:

bash <path-to-neo-releases>/symlink-skills-win-git-bash.sh

Replace both paths as on Linux or Mac. For example, if you cloned both repositories into C:\projects, in Git Bash it would be cd /c/projects/techstore-tests and then bash ../NEO-releases/symlink-skills-win-git-bash.sh.

How to know it worked: at the end, the console shows the list of skills, and each one must appear with the type <SYMLINKD> (symbolic link to a folder). For example:

 Directory of C:\projects\techstore-tests\.claude\skills

09/28/2026  10:15 AM    <SYMLINKD>     lippia-neo-create-test-plan [C:\projects\NEO-releases\skills\lippia-neo-create-test-plan]
09/28/2026  10:15 AM    <SYMLINKD>     lippia-neo-read-user-story [C:\projects\NEO-releases\skills\lippia-neo-read-user-story]
09/28/2026  10:15 AM    <SYMLINKD>     lippia-neo-meta-run-user-story-e2e [C:\projects\NEO-releases\skills\lippia-neo-meta-run-user-story-e2e]
...
What you see What it means What to do
Each skill appears as <SYMLINKD> ✅ The links were created correctly Continue with the next step
The skills appear as <DIR> They're copies, not links: they won't be updated with git pull Delete the .claude/skills folder and run the script again from Git Bash as administrator
Operation not permitted error when creating the links Git Bash doesn't have administrator permissions Close Git Bash, open it with Run as administrator, and run the script again
No such file or directory error when running the script The path to NEO-releases isn't correct from where you are Check where you cloned NEO-releases (Step 4) and fix <path-to-neo-releases>

The scripts create the links for Claude Code (the .claude/ folder). If you use Codex or Copilot on Windows, change ASSISTANT=claude to ASSISTANT=codex or ASSISTANT=copilot in symlink-skills-win-git-bash.sh before running it. The Linux or Mac script only creates .claude/ for now.

IMPORTANT: if you're on Option A (VSCode with the Claude Code extension), after creating the skills you need to reload VSCode so they can be seen.

6.3 Check that your assistant can see them

Open a session with your AI assistant on the test repository and write to it, in natural language:

List the available Neo skills

If the installation went well, your assistant will reply with the list of skills (lippia-neo-read-user-story, lippia-neo-create-test-plan, lippia-neo-meta-run-user-story-e2e, etc.).


Step 7. How to configure the Playwright MCP

Playwright is the tool that actually opens a browser (Chrome, Firefox, etc.), navigates through the app under test, clicks, fills in forms, and checks results. It's the "executing arm" that the skills use behind the scenes when the project is configured with this framework.

For the next steps, you need to open a terminal, just like you did before:

(Option A only)

In VSCode, open the integrated terminal from the Terminal → New Terminal menu (or the shortcut Ctrl+`).

(Option B only)

  • Windows: search for "Git Bash" in the start menu and open it.
  • Mac: open the Terminal app.

Then, in that terminal, navigate to the root folder of the test repository (where its package.json file is — not NEO-releases):

cd /path/to/test-repository

7.1 Install the project dependencies

npm install

This downloads the libraries the project already has declared.

7.2 Install the browser for the exploration stage

This step downloads the Chromium, Firefox, and WebKit browsers. You only need to run it once per computer (or when the project's Playwright version changes).

Besides running the tests, your assistant uses its own browser to explore the app manually before generating the tests:

npx @playwright/mcp install-browser chrome-for-testing

Step 8. Data for the environment under test (URL and credentials)

The skills need to know which URL to test against and with which user. You need to fill in this data in a .env file (which is never pushed to the repository — it's in .gitignore), at the root of the test repository:

# .env
APP_BASE_URL=https://your-app-under-test.com
APP_USERNAME=test-user
APP_PASSWORD=test-password

If you don't have this file yet, that's not a problem: we'll generate it in the next step, when you run the project configuration skill.


Step 9. Configure the project with NEO

At this point, we're ready to start using the NEO skills. To do so, we'll open the AI assistant we configured in Step 2, on the test repository.

9.1 Open the assistant on the test repository

(Option A only)

  1. In VSCode, open the AI assistant with the Claude icon located in the top bar.
  2. Check that VSCode is pointed at the test repository.
  3. Start a new chat.

(Option B only)

  1. Open the Claude Code Desktop app.
  2. In the top-left corner, click the </> Code button.
  3. Select the local folder of the test repository that you cloned in Step 4 — this tells the assistant which repository (and which branch) you're going to work on.

9.2 Run lippia-neo-bootstrap-stack

Applies to both options (A and B).

In the chat, run the first command:

/lippia-neo-bootstrap-stack

What happens: the assistant analyzes the repository to determine which technologies the project is built with. Anything it can't infer on its own, it will ask you.

Some data it infers and only proposes to you as a suggestion:

  • Operating system of the test environment and base URL of the application under test — with this, it puts together a first configuration proposal, which you'll be able to adjust later.
  • Build version of the app to test — it takes this from package.json and suggests it to you.

Others are specific questions, with options to choose from:

It asks you Options What it means
Authentication method [1] Basic Auth (username and password, the ones you defined in Step 8) · [2] Google SSO · [3] API Token · [4] Ninguno · [5] Otro Choose the one your app under test uses
Where to get the user stories from [1] Local · [2] Cloud (Jira, etc.) · [3] Otro Depending on what you choose, it will ask you for the details in the next step — for example, the name of a folder or the access URL of a repository
User stories directory (if you chose "Local") Suggests the specs/ folder (creates it if it doesn't exist) You can accept the suggestion or specify another folder
Which directory are the test plans saved in (test_plans_dir)? [1] test-plans/ (default) · [2] docs/test-plans/ · [3] Otro This is where the step-by-step breakdown of the agent's reasoning is stored
Which directory is the executable test suite generated in (tests_dir)? [1] tests/<test_framework>/ (default — e.g. tests/playwright/, tests/cypress/, tests/lippia/) · [2] docs/tests/ · [3] Otro (path relative to the repo root) This is where the automated tests (.js) are created, which you can run again later
Which directory are the final reports written to (reports_dir)? [1] test-results/reports/ (default) · [2] docs/test-results/reports/ · [3] Otro (path relative to the repo root) This is where the report with the results of the manual and automated tests, the risk analysis, etc. is saved
Which directory do the manual execution report + screenshots go in (scripted_dir)? [1] execution/ (default) · [2] docs/execution/ · [3] Otro (path relative to the repo root) This is where the execution results are saved

What you'll have at the end of this step: the qa-stack.yaml file, with all the information gathered about the project that's needed to run the plans from here on.


Step 10. Run lippia-neo-meta-run-user-story-e2e to start the full QA flow

Trigger: lippia-neo-meta-run-user-story-e2e

What happens: starting from a user story, this step generates the automated tests and runs them.

  1. In the chat with your assistant, write a prompt like this one:

    Here is some information, I just want you to keep it as context:
    I want to run the full end-to-end flow for the story user-stories/PA-US-03.md.
    
  2. Replace user-stories/PA-US-03.md with the real path and name of the file that contains your user story.

What you'll have at the end of this step: the generated automated tests and their results, saved in files inside the folders you configured in Step 9 (tests_dir, reports_dir, etc.).