K0lmenIA documentation

QA agents for Claude Code: test design, automation with k0lmena and integration with Xray, QMetry, AIO Tests and Azure DevOps.

What is K0lmenIA

A team of QA-specialized agents for Claude Code, designed for manual testers: no coding needed, you work by chatting inside VS Code.

You provide an input (a story, a bug observation, an API contract, a Jira key or a Figma link), ask for what you need in plain language and the right agent produces the result: analysis, plans, cases in Excel or Gherkin, data, bugs, HTML reports, automation and upload to the test management tool.

Architecture

How to use it

1. Add your inputs in input/, or pass a Jira key, a Confluence page or a Figma link with the connector enabled.
2. Ask in plain language. Claude Code picks the agent; you can also name it.
3. Review the result in output/ or herramientas/k0lmena/.
4. Automate what repeats and run it with npm test as often as you like, with zero tokens.

See the catalog of all 28 agents

Requirements

Install only what you'll use.

Installation

1. Install Claude Code

curl -fsSL https://claude.ai/install.sh | bash    # macOS / Linux
npm install -g @anthropic-ai/claude-code          # alternative
claude --version

On Windows, follow the official guide.

2. Clone the repository

git clone https://github.com/underc0delabs/k0lmenIA.git
cd k0lmenIA
pip install -r requirements.txt     # Mac/Linux: pip3
npm install                         # k0lmena
cp .env.example .env                # and fill it in (PowerShell: copy)

3. Check everything is ready

npm run doctor    # tells you what's missing and how to fix it

4. Open VS Code and launch Claude Code

code .
claude      # asks you to sign in the first time

5. Add optional pieces

npx playwright install              # live E2E runs
npm install -g newman               # Postman
cd herramientas/k0lmena
npx playwright install chromium     # + firefox webkit (cross-browser)
npm run bootstrap:k6                # k6
npm run bootstrap:jmeter            # JMeter (Java 8+)

Configuration: the .env file

There is a single .env at the repo root, used by the agents, k0lmena and the management scripts. It is in .gitignore and the commented template is .env.example.

Context research and "missing information"

Before analyzing, planning, writing cases or automating, agents research the story's full context: Jira description and criteria, every comment, subtasks, epic, linked issues, Confluence, Figma, contracts and the input/ folder. The result is a reusable context sheet in output/contexto/.

Every value not found in any source gets an ID (FI-01) with what's missing, where it was searched, what it affects and the question for the PO. The same ID travels to the case spreadsheet, the .feature files (@falta-info @FI-01 tags), reports and the closing report. The application is never used as a source of requirements.

Automation with k0lmena

The framework ships in herramientas/k0lmena/. A mapper agent walks through the app once and writes the automation; from then on the suite runs with npm, without agents and with zero tokens.

cd herramientas/k0lmena
npm test                       # web + API
npm run test:web               # also: test:api · test:mobile · test:all
TAGS=@HU-001 npm test          # filter by tag
npm run report:web             # also: report:api · report:mobile

If a step can't be executed, the scenario is tagged @bloqueado with the reason and won't run until it's resolved.

Performance

The performance-mapper builds load, stress, soak and spike tests. It never uses defaults: it walks you through goal, tool, environment, users, ramp-up, duration and thresholds, and asks for confirmation before every loaded run.

npm run perf                             # lists scripts
npm run perf -- <script> smoke           # validates with minimal load
npm run perf -- <script> load            # target load (asks to confirm)
npm run perf -- <script> stress --confirmar

Xray, QMetry, AIO Tests and Azure DevOps

gestor-pruebas and publicador-resultados work with Xray Cloud, Xray Server/Data Center, QMetry for Jira (QTM4J) and AIO Tests using the same commands. Configure it in .env with GESTION_HERRAMIENTA (xray-cloud, xray-dc, qtm4j or aio) and GESTION_PROYECTO.

python scripts/gestion/gestion.py --dry-run carpeta --ruta "HU-001 Registro"
python scripts/gestion/gestion.py subir-casos --origen <casos.xlsx> --carpeta "HU-001 Registro" --historia PROJ-12 --traza HU-001
python scripts/gestion/gestion.py crear-ciclo --nombre "Sprint 5" --historia PROJ-12 --traza HU-001
python scripts/gestion/gestion.py publicar-resultados --ciclo PROJ-60 --resultados <resultados.json> --traza HU-001

Azure DevOps Test Plans integrates through its official MCP connector using ADO_ORGANIZACION, ADO_PAT and ADO_PROYECTO: agents read stories and the Wiki, and create Test Cases linked to a suite.

Database verification

The verificador-datos checks what was stored, in which state and with which values, in PostgreSQL, MySQL / MariaDB, SQL Server and MongoDB, with several named connections. It is read-only by default, masks sensitive data and requires explicit enabling and confirmation to write.

DB_CONEXIONES=principal,pagos
DB_PRINCIPAL_MOTOR=postgres        # postgres | mysql | mariadb | sqlserver | mongodb
DB_PRINCIPAL_HOST=localhost
DB_PRINCIPAL_PUERTO=5432
DB_PRINCIPAL_BASE=tienda
DB_PRINCIPAL_USUARIO=qa_lectura
DB_PRINCIPAL_ESCRITURA=no
DB_PRINCIPAL_PRODUCCION=no

Web quality: exploratory, accessibility, performance, visual, cross-browser and security

MCP connectors

npm run conector                          # lists available connectors
npm run conector -- activar azure-devops  # enables one (just for you)

Then restart Claude Code and check the connection with /mcp.

Conventions

Troubleshooting

I don't know what's missing

Run npm run doctor: it checks Python, Node, k0lmena, Playwright, Newman, Java, Docker, .env and connectors, and tells you how to fix what's missing.

An agent replies "I need you to confirm"

It's by design: subagents can't ask mid-task. Answer and Claude resumes with the same agent.

npm test runs 0 scenarios

You haven't automated anything yet (folders start empty) or the TAGS filter matches no scenario.

An MCP connector won't connect

Variables must be in the environment where you launch claude. Atlassian and Figma are authorized from /mcp.

See all troubleshooting entries in the full documentation

Extending the project

• Agent: a .claude/agents/my-agent.md file with name and description; Claude Code uses the description to decide when to call it.
• Skill: a folder in .claude/skills/ with its SKILL.md.
• MCP connector: an entry in .mcp.json, with no secrets.
• Tool: a subfolder in herramientas/ with its README.

License

K0lmenIA is open source under the MIT license. Built by the QARMY and Underc0de community.